Invoices and billing
Mapbox provides Pay-as-you-go customers an invoice for all costs accrued each month. An account's invoices page contains monthly invoices and billing history.
To access the account's, log into the account and navigate to account.mapbox.com/invoices.
What to expect
Mapbox accounts are free to create, and all customers with Pay-as-you-go billing receive a monthly free tier of services that resets on the first day of the account's monthly billing period. We will send an email notification to the account's email address the first time a free tier is exceeded during each billing period.
Every month, a new invoice is generated on the first day of a new billing period. This upcoming invoice is generated even if an account has not yet incurred overages for that billing period. Usage data is reflected on the upcoming invoice within 24 hours, and charges are always in USD.
Invoices will be finalized on the last day of the account's billing period. When your invoice is finalized, your payment method on file is automatically charged. If the charge fails, the account will be at risk of deactivation and service interruptions. By using Mapbox services, you agree to pay all fees associated with the services.
The invoices page provides insight into an account's monthly billing period. Billing periods start on the first day of the month and end on the last day of the month (for example: May 1 - May 31, September 1 - September 30).
Shortened first month
The account's billing period will be shortened during the first month of account creation or account reactivation. For example, if the account is created or reactivated on September 15, the first billing period will be September 15 - September 30. Every following billing period will be from the first day of the month to the last day of the month (November 1 - November 30, December 1 - December 31, etc).
Most Mapbox services include a free tier of services available to all accounts during each billing period. The number of requests, elements, users, sessions, or other units included in the free tier varies by Mapbox product. You can review the free tier for each product on the Pricing page.
Each invoice listed on an account's invoices page includes the following:
- Invoice Number: a unique identifier, distinct for each Mapbox invoice.
- Status: the status of the invoice. View all possible invoice statuses.
- Invoice Date: the date on which the invoice will be finalized. This is the date on which the amount due will be charged to the account's credit card or prepaid credit.
- Amount Due: the total dollar value in USD due for all services, after factoring in bulk discounts (if applicable).
- Pay button: a link to a secure, self-serve portal for paying a
Past Dueinvoice, hosted by our payment provider.
Each Mapbox invoice displayed on the invoices page includes an invoice status, indicating:
|The invoice has been successfully paid.|
|This is the account's current invoice. The current invoice is still actively being updated with usage from the current billing period, and has not yet been finalized.|
|This invoice has not yet been paid, and is past its due date.|
|The invoice is awaiting payment according to the account's payment terms. Only available for Monthly Invoicing customers.|
|This invoice will likely not be paid. Invoices can only have this status if the Mapbox Support team has taken action on the invoice.|
|This invoice contains a mistake and does not require payment. Invoices can only have this status if the Mapbox Support team has taken action on the invoice.|
Past Due invoice will automatically be retried multiple times over a short grace period. During this grace period, we will send multiple email notifications detailing any failed charges and reminding the account holder about the upcoming deactivation. If the invoice is still
Past Due after the final charge attempt, the account will be deactivated. When an account is deactivated, all access tokens and Mapbox services are immediately suspended until the account is reactivated.
Reactivating an account
An account that has been deactivated will be locked until a valid payment method is entered into the persistent pop-up on account.mapbox.com.
Reactivating your account will not automatically pay
Past Due invoices. To pay
Past Due invoices, navigate to your invoices page and click the Pay button.
Structure of invoices
Each Mapbox invoice includes three kinds of information:
- Account information: including the email address, VAT Tax ID, and Purchase Order Number associated with an account and any additional information that has been added to the invoices.
- Invoice information: including the status, date issued, payment due date, billing period, and a unique invoice number.
- Usage information: including line item for each service for which the account's usage exceeded what is included in the free tier, and any applicable volume-based discounts.
Details of charges
If an account has a recurring subscription or service overage charges, there will be line items listing those services. See an example line items below:
The product identifies the product the account is using. The quantity for each line item on the invoice will reflect amount of the usage accrued throughout the billing period. The unit describes the billing units associated with the quantity used. The cost will show the total amount in USD for that product, and you can click to see details about how that total was calculated with any applicable discount tiers.
To learn more about how applications built with various Mapbox tools translate to particular line items, see the pricing by products guide.
If a discount has been applied to an account, it will be displayed as a
discount line item on the invoices during each billing period in which the discount is active. Information about the discount's expiration date can be viewed in the billing settings.
Preview line items
One type of line item that may be included on an account's invoices are "preview line items." Preview line items are free and provide insight into the costs for beta products which have not launched in general availability yet. Once the beta product has launched in general availability, the costs will no longer be free. When viewing an invoice, it's possible to toggle preview line items
on to visualize future costs, or toggle them
off to focus on currently billable products. You will only see preview line items if the account is using beta products.
If a Mapbox service updates their preview pricing, only invoices with
Upcoming status on or after the date of the update will reflect the updated preview pricing. Changes to preview pricing are not backfilled on any of an account's
Past Due invoices.
Downloading or printing invoices
To download or print the invoice:
- Log into the account and navigate to the invoices page.
- Open the invoice you want to download/print.
- Click the Print button and use the print options to save the file as a PDF.
Adding custom information to an invoice
To add a Purchase Order Number (PO Number), VAT Tax ID, or other optional information to all future invoices, follow these steps:
- Log into the account and navigate to the settings page.
- Enter the PO Number, VAT Tax ID, and/or a billing email address in the appropriate text fields.
- Enter any additional optional information in the
- Click Save changes.
The default payment setting for all customers is automatic payments. With automatic payments, the account's credit card on file (or prepaid credit) will be automatically charged when the Upcoming invoice is finalized. Mapbox accepts the following credit, debit, prepaid, and gift cards: Visa, MasterCard, American Express, JCB, Discover, and Diner's club.
If you do not have access to a credit or debit card, consider using a prepaid card available from several vendors, including:
If your organization is unable to make payments with a credit card, contact our Sales team to learn more about the requirements for the Monthly Invoicing beta program.
Monthly Invoicing is in public beta. There are minimum monthly spending requirements to qualify for the beta. To learn more about the spending requirements and enroll in the beta, contact our Sales team.
With Monthly Invoicing, the account's invoice is not automatically charged to a credit card on file. Instead, an invoice is emailed to the account's billing email address. The invoice then must be paid promptly.
When an account is enrolled in Monthly Invoicing, the option to add a billing email address will automatically appear in the account settings page.
Monthly Invoicing is not available for all customers. To qualify for Monthly Invoicing, you must be working with a Mapbox Account Manager and your account must be in good standing. Reach out to our Sales team to inquire about Monthly Invoicing options for your organization.
Add or update payment method
You can add or update a credit card on an account by visiting the billing settings and clicking the Add payment method button or the Edit button if you are updating the credit card.
You can add prepaid credit to be used for future Mapbox services. Prepaid credit can be added any time and cannot be refunded in the case it's no longer needed. Account credit will be applied to future invoices on a recurring basis until the credit is $0.00. Mapbox won't charge the credit card on file until the account's prepaid balance is $0.00.
To add prepaid credit to the account, follow these instructions:
- Navigate to the billing settings.
- Make sure you have a valid credit card on file.
- Click the Add credit button.
- Enter the amount of credit you want to buy.
- The credit card will be charged immediately, and the account's email address will receive a receipt for the payment.
- After buying credit, a record will be available in the billing settings and on the
If an account has experienced a failed payment, prepaid credit cannot be used to pay a
Past Due invoice. The account balance will only be applied to invoices with
Upcoming status or an invoice date in the future. To pay a
Past Due invoice directly, please see the troubleshooting section.
Coupon codes can be added to the account's billing settings. Only one coupon can be active at a time.
Non-profit and educational discounts
The Mapbox Community team provides tailored support for non-profits, educational institutions, and positive-impact organizations. If you need a discount for your positive-impact project please contact the Community team.
If Mapbox has issued a refund, the funds will be returned to the account's original payment method 5-10 business days after the refund has been processed. Individual Mapbox invoices will not be reflected to show refunds - if you require additional receipts for the refund, please reach out to our support team.
The following billing emails will be sent to the profile email address that is registered under the account's main settings even if the account is enrolled in the Monthly Invoicing beta:
Exceeded free tier
[Mapbox Billing] Usage notification
Mapbox sends the exceeded free tier email when an account's usage exceeds one or more of a service's free tier during a billing period, we will send an email with the subject. This notification is a courtesy notice sent to all accounts the first time a free tier is exceeded during a billing period, even if there is a valid payment method or adequate prepaid credit on file.
[Mapbox Billing] Successful payment receipt
Mapbox will send a payment receipt for all successful payments. The email will include a link to download a PDF payment receipt.
[Mapbox Billing] payment failure
Mapbox will send a series of failed payment emails every time a payment fails. The emails include instructions for updating your registered payment method or paying an unpaid invoice with a secure, one-time payment page. See the troubleshooting section for more detailed recommendations.
[Mapbox Billing] Account deactivation notice
If an account as been deactivated for failed payments, Mapbox will send a deactivation notice. This email includes a link to add or update the account's payment method, which will reactivate the account and restore Mapbox services.
Updated payment information
[Mapbox Billing] Your payment info has been updated
Mapbox sends a notification when the account's payment method is updated.
[Mapbox Billing] Your coupon expires soon
If the account has a discount applied, Mapbox will send an email reminder when the coupon is within 10 days of expiring.
[Mapbox Billing] Low credit notice
Mapbox will send a low credit notice when the prepaid credit balance is low. The low credit notice includes the account ID, the account balance (amount of credit remaining), and a link to the account's billing settings where you can add more credit.
Below are common feature requests. If any of these features are important to you, let us know.
Secondary billing email addresses
Secondary billing email addresses can be used to share invoices directly with your Finance departments or with clients. Secondary billing emails are only available to customers on Monthly Invoicing. For all other customers, Mapbox recommends using a group or alias email address for the account or setting up a forwarding rule in your email provider that automatically forwards billing emails to relevant stakeholders.
You can also consider using a group or alias email address like
email@example.com for your account and granting multiple people access to that address so additional stakeholders have visibility into account notifications like billing emails.
Mapbox does not yet offer configurable usage notifications via email or SMS notifications. For example, there is no option to send an email when the account reaches 50% of any product's free tier during the billing period.
Mapbox accounts do not support a spending cap customizable usage limit after which services cut off during a billing period.
For now, you can create predictable monthly spending by adding a set amount of prepaid credit and monitoring the statistics and invoices closely. Once an invoice reaches an amount you'd like to pay for that billing period, you can rotate the account's access tokens (deactivating older tokens).
When access tokens are rotated, production maps will become deactivated and the requests from the deleted tokens will fail. When the new billing period begins, rotate the new tokens into Mapbox implementations to resume service usage.
Credit card decline
To protect your privacy, banks don't give detailed information to Mapbox when credit card payments fail. If the card information seems correct, contact your bank to ask for more information or to allow payments to Mapbox.com. If payments are still being declined after contacting your bank, try adding a different credit card for the payment.
Contact our support team to let us know when you're working with your bank so we can help prevent account deactivation to keep your account's Mapbox services live.
Insufficient prepaid credit
If an account has prepaid credit on file but the credit balance is not enough to cover the full amount due for an invoice, Mapbox will charge the remaining amount to your credit card on file. In these cases, if there is no valid credit card on file as a secondary payment method or the credit card charge fails, the invoice will remain
Past Due and the account will be at risk of deactivation.
To prevent deactivation, add or update the credit card on the account. Prepaid credit cannot be used to pay for an invoice that has already finalized.
Paying invoices with
Past Due status
To pay invoices with
Past Due statuses:
- Log into the account.
- Navigate to the account's invoices page.
- Click the Pay button next to any invoice with a
- Paying via the Pay button will not save or update the credit card on the account.
- Prepaid credit cannot be used to pay
- Mapbox reserves the right to retry charges for
Past Dueinvoices based on the Mapbox Terms of Service.
Mapbox invoices are issued in USD. An invoice with
Paid status will display the total paid in USD, even if your payment processed in another currency. If you are comparing a financial statement from a credit card or bank to a Mapbox invoice and the amounts are not aligned, apply the exchange rate on the date of the charge for your currency to USD.
What information should I include in my support request?
If you cannot resolve an issue or have outstanding questions not answered in this documentation, we're happy to help with your questions. We can provide the most prompt resolution when you include the following information in your support submission:
- Invoice Number
- Invoice Date
- Account ID or registered email address
- Explanation of the issue you are experiencing
- What you've already tried to remedy the situation