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 Invoices page, 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. By using Mapbox services, you agree to pay all fees associated with the services.

Every month, a new invoice is generated on the first day of a new billing period and is available on the account's Invoices page. Invoices are in USD. Usage data will be available on upcoming invoices within 24 hours. Invoices are automatically posted to an account's Invoices page even if an account has not incurred charges for that billing period.

Invoices will be charged to the account's payment method on their due dates. If a payment fails, an account is at risk of deactivation.

Billing period

An account's monthly billing period:

  • Is one month long.
  • Begins on the day a Mapbox account is created.
  • Will reset if you change plans or reactivate your account after an account deactivation. Your new billing period will begin on the day your plan changes or is reactivated.

Invoices will be automatically posted to your Invoices page and charged to the account's payment method on their due dates. You can find an account's monthly billing period on the Invoices page. The due date on your upcoming invoice marks the day the account's monthly billing period renews.

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, or sessions included in the free tier varies by Mapbox product. You can see the free tier for each product on the Pricing page.

  • Using only the free tier: If an account has not exceeded the free tier for any services during the billing period, there will be a $0 invoice displayed on the Invoices page.

  • Exceeding the free tier: If an account exceeds the free tier for any service, additional units are automatically served at the rates described on the Pricing page and are reflected on the account's upcoming invoice. See the structure of invoices documentation for details about how products used during the previous billing period are displayed.



  • Upcoming: This is the account's next invoice.
  • Paid: The invoice has been paid successfully.
  • Unpaid: This invoice is unpaid and will be automatically retried.
  • Closed: This invoice is unpaid, contact Billing Support for payment options.

Account deactivation

An Unpaid invoice will automatically be retried three times over a short grace period. If the invoice is still Unpaid after the final retry, the account will be deactivated. When an account is deactivated, all access tokens and Mapbox services are 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 Once the account is reactivated, the failed invoice will keep the Closed status. Please contact our support team for payment options.

Structure of invoices

Each monthly 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, billing period, and an invoice ID.
  • Usage information including line item charges 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 listed under Details of charges. See an example line item charge 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 as outlined on the pricing page.

Line items

The line items on an invoice may not have the same name as the Mapbox products you used to build the applications. For example, if you built a web application with Mapbox GL JS, the line items can vary based on the version of Mapbox GL JS that was used, and could be displayed as Map Loads for Web, Vector Tiles API requests, or Raster Tiles API requests.

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 account's 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. An invoice that is covered by a 100% off discount with be displayed on the Invoices page as a $0 invoice.

Preview line items

One type of line item that may be included on an account's invoices are Preview line items. These line items provide insight into the costs that will be associated with usage of a beta product when that product's pricing is finalized and launched in general availability. When viewing an invoice, it's possible to toggle Preview line items on to visualize future costs, or toggle them off to focus on your total, current billable charges. Preview line items will only be included on an invoice if the account has used a beta service that is offering Preview line items within that invoice's billing period.

Calculating costs

The price per billable unit depends on the total usage an account has accrued for that product. You can see a breakdown of the exact number of billable units at each price by clicking the icon in an invoice.

For more information on what's included in the free tier and costs associated with additional service consumption, visit our Pricing page.

Managing invoices

You can view and print invoices from the Billing page. Customers with an annual agreement are invoiced through the Mapbox Finance team.

Downloading or printing invoices

Log in to the account, navigate to, open each invoice individually, click the print button, and use the print options to Save to 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 additional info link at the top of the page under the account's email address.
  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 invoices - including those that have already been paid, are upcoming, and will be created in the future.


Available payment methods

Mapbox invoices can be paid with prepaid credit as well as the following credit, debit, prepaid, and gift cards on a recurring basis: Visa, MasterCard, American Express, JCB, Discover, and Diners Club.

If you do not have access to one of these cards, consider using a prepaid card instead. Prepaid cards are available from several vendors, including:

Add or update payment method

You can add your payment information by visiting your Billing page and clicking the Add payment method button.

If you need to update an account's payment method, you can do so from the Billing page. Click Edit and enter new credit card information.

Prepaid credit

Prepaid credit is a method of adding funds to an account that are used to pay monthly invoices, instead of recurring credit card charges. Prepaid credit can be added any time and cannot be refunded in the case it's no longer needed.

Note that prepaid credit cannot be used to pay Closed invoices or invoices past their due date, only for invoices dated in the future. For help paying a closed invoice, please see the troubleshooting section.

Account credit will be applied to future invoices on a recurring basis until the credit is exhausted. We won't charge your primary payment method until you run out of credit.

  1. Navigate to your Billing page.
  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. Your credit card will be charged immediately.
  6. After you buy credit, a record will be available in the Billing settings and on the Upcoming invoice.

An invoice that is covered entirely by prepaid credit will be displayed on the Invoices page as a $0 invoice. Click into individual invoices to view the details of charges, costs per service, and applicable high volume discounts.

If an account has an insufficient amount of prepaid credit on file to cover a full invoice and there is not a valid credit card on file as a secondary payment method, the invoice will not process successfully and the account is at risk of deactivation. To prevent deactivation, add a credit card to the account or contact our support team for help.


If you've received a coupon code, you can use it when you sign up or upgrade your account on your Billing page after you've filled in your payment details.

Non-profit and educational discounts

We do not offer a specific plan for non-profit or student users. Instead, our 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 we have issued a refund for an account, the funds will be returned to the account's original payment method 5-10 business days after the refund has been processed and we will send the registered email address on an account a receipt from Stripe (our payment processor). 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

Exceeded free tier

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 "[Mapbox Billing] Usage notification" to the account's registered email address. 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. Each email includes a link to the upcoming invoice - click through to see the details of charges as well as the amount of prepaid credit available to pay the invoice and any relevant discounts applied to the invoice.

Successful payment

The account's registered email address will receive a notification with the subject "[Mapbox Billing] Successful payment receipt" for all successful invoices and charges. The email will include a link to download a PDF payment receipt.

Failed payment

If an account exceeds the requests included in one or more free tiers and there is insufficient prepaid credit available, no valid credit card on the account, or the credit card on file has been declined, we will send the account's registered email address a series of notifications that include "[Mapbox Billing] payment failure" in the subject. The emails include instructions to 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

When an account is deactivated for failed payments, we will send a notification with the subject [Mapbox Billing] Account deactivation notice to the account's registered email. This email includes a link to add or update the account's payment method, which will reactivate the account and restore Mapbox services.

After an account has been reactivated, we will send a notification with the subject [Mapbox Billing] Pay outstanding invoice that includes a link to a secure, one-time payment page.

Coupon expiring

If the account has a discount applied, we will send a notification with the subject [Mapbox Billing] Your coupon expires soon when the coupon is within 10 days of expiring.

Low credit

If you have added prepaid credit to your account with a credit card payment, your account will receive an email notification when the credit balance is low. The email will be delivered with the subject [Mapbox Billing] Low credit notice to the registered email address on the account when the credit balance is less than two invoices. The low credit notification includes the ID of the account, the amount of credit remaining, and a link to your billing settings where you can add more credit.

Feature requests

Secondary billing email addresses

We will email the account's registered email address with invoice notifications as described in schedule of charges.

It is not possible to add a separate billing email address to an account. To automate sharing receipts internally or with clients, we recommend using a group or alias email address for the account or setting up a forwarding rule in your email provider that automatically forwards emails with the subject "[Mapbox Billing] Successful payment receipt" sent to the account's registered email address to other 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. Let us know if this feature is important to you!

Spending alerts

When an account exceeds one or more free tiers in a billing period, we will send an email with the subject "[Mapbox Billing] Usage notification" to the account's registered email address. Mapbox does not yet offer configurable usage notifications via email or SMS notifications. Let us know if this is a feature you'd like to see!

Spending cap

Mapbox accounts do not support a "spending cap", "charge ceiling", or customizable "limit" after which services cut off during a billing period. If you would find a feature like this beneficial, please contact our team describing the use case so we can share the request with the team.

For now, you can create predictable monthly spending by adding a set amount of prepaid credit and by monitoring the account 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 (making older tokens invalid).

When access tokens are rotated, production maps will become deactivated and the requests from the deleted tokens will be rejected - generated no further charges. When the new billing period begins, rotate the new tokens into Mapbox implementations to resume service usage.


Credit card decline

Unfortunately, banks don't offer us detailed information when a credit card is declined. Check to make sure your credit card is valid, up to date, and within its spending limit for the month. If the card information seems correct, contact your bank, inquire for more information, and ask for future charges to be accepted. If payments are still being declined after contacting your bank, you may need to try uploading 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 it's not enough to cover the full total due for an invoice, our systems will fallback to the credit card on file to try and process the rest of the charge successfully. In the case that there is an insufficient amount of prepaid credit and there is not a valid credit card on file as a secondary payment method, the invoice will not process successfully and the account is at risk of deactivation.

To prevent deactivation, add a credit card to the account, or pay the invoice with the secure hosted URL that you receive from [Mapbox Billing] via email. Please get in touch with our support team for help.

Paying a closed invoice

When all scheduled attempts to pay an invoice fail and the account is deactivated, the unpaid invoice will be marked with Closed status on the account's Invoices page. While a valid credit card must be entered to reactivate the account, the Closed invoice will not immediately be retried. Following reactivation, we will send the account's registered email address a link to a secure payment page so you can pay the Closed invoice.


Prepaid account credit cannot be used to pay Closed invoices.

Please contact our support team to let us know when we can retry payment for a Closed invoice. Our team reserves the right to retry charges for Closed 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. If you still have questions about currency, contact support.

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 ID
  • Invoice due 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?