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

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.

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.

Billing period

The invoices page provides insight into an account's monthly billing period. Billing periods are:

  • One month long (ex: May 10 - April 9, April 10 - May 9)
  • Begin on the day a Mapbox account is created.
  • Will reset if the account is reactivated after an account deactivation. The account's new billing period will begin on the day of reactivation.

The invoice date on an account's upcoming invoice is the day the billing period will renew. Each individual invoice provides a link to View statistics for this period - when clicked, all usage for that billing period is visualized on the Statistics page.

Free tiers

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.


Understanding invoices

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 Due invoice, hosted by our payment provider.

Invoice statuses

Each Mapbox invoice displayed on the invoices page includes an invoice status, indicating:

PaidThe invoice has been successfully paid.
UpcomingThis 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.
Past DuePayments for this invoice have failed and are still due.
UncollectibleThis invoice will likely not be paid. Invoices can only have this status if the Mapbox Support team has taken action on the invoice.
VoidThis 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.

Account deactivation

A Past Due invoice will automatically be retried three 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

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 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:

Optimization API:
cost and details

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.

Line items

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 Paid or Past Due invoices.

Downloading or printing invoices

To download or print the invoice:

  1. Log into the account.
  2. Navigate to the invoices page.
  3. Open the invoice you want to download/print.
  4. Click the Print button and use the print options to save the file as a PDF.

Adding custom information to an invoice

When an organization name is added to an account's settings, this name will populate on all the account's invoices. Additionally, you can provide optional contact information, VAT details, or project information to all of an account's invoices by following these steps:

  1. Log in to the account and navigate to the invoices page.
  2. Open any individual invoice.
  3. Click the Add memo link above the Details of charges.
  4. In the text field, enter the custom information to be included on all invoices. Click Update additional info to save the entry.

The additional information will now appear on all past and future invoices - including those that are Paid, Past Due, and Upcoming.


Payment setting

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 discuss annual invoicing options.

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.

Prepaid credit

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:

  1. Navigate to the billing settings.
  2. Make sure you have a valid credit card on file.
  3. Click the Add credit button.
  4. Enter the amount of credit you want to buy.
  5. The credit card will be charged immediately, and the account's email address will receive a receipt for the payment.
  6. After buying credit, a record will be available in the billing settings and on the Upcoming invoice.
Prepaid credit cannot be applied to an `Past Due` invoice

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.

Billing emails

All billing emails will be sent to the email address that is registered under the account's billing settings. Review all possible billing emails below:

Exceeded free tier

Email subject: [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.

Successful payment

Email subject: [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.

Failed payment

Email subject: [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.

Account deactivation

Email subject: [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.

Coupon expiring

Email subject: [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.

Low credit

Email subject: [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.

Feature requests

Below are common feature requests. If any of these features are important to you, let us know.

Secondary billing email addresses

It is not possible to add a separate billing email address to an account. To automate sharing receipts internally or with clients, 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 for your account and granting multiple people access to that address so additional stakeholders have visibility into account notifications like billing emails.

Spending alerts

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.

Spending cap

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 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:

  1. Log into the account.
  2. Navigate to the account's invoices page.
  3. Click the Pay button next to any invoice with a Past Due status.
  • Paying via the Pay button will not save or update the credit card on the account.
  • Prepaid credit cannot be used to pay Past Due invoices.
  • Mapbox reserves the right to retry charges for Past Due invoices 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
Was this page helpful?