Skip to main content

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

Billing period

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).

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 DueThis invoice has not yet been paid, and is past its due date.
OpenThe invoice is awaiting payment according to the account's payment terms. Only available for Monthly Invoicing customers.
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 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.

Current Month Usage

If your account is deactivated in the middle of a billing cycle, an invoice will be created containing the usage accumulated so far from that cycle. This invoice will be added alongside your other previous invoices and must be paid for your account to be 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 and all Past Due invoices on the have been paid.

To pay Past Due invoices, navigate to your invoices page and click the Pay button. You cannot reactivate your account until you have paid your Past Due invoices.

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:

Optimization API:






$9.50 chevron-down

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 chevron-down 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 active 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 added 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 and navigate to the invoices page.
  2. Open the invoice you want to download/print.
  3. 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:

  1. Log into the account and navigate to the settings page.
  2. Enter the PO Number, VAT Tax ID, and/or a billing email address in the appropriate text fields.
  3. Enter any additional optional information in the Memo section
  4. Click Save changes.

Sales tax and VAT information

Services provided by Mapbox are subject to being taxed depending on the location of your company address and products consumed. For instance, customers based in the United States may be charged US Sales Tax. Those in the European Union, South Korea, Taiwan, and some other countries may be charged VAT instead.

Mapbox will not apply taxes to services provided for customers who provide valid tax exemption documentation.

U.S. sales tax

U.S. customers may be subject to state and local sales taxes. Sales tax charges will be included as a line item on your invoice.

States where products and services of Mapbox, Inc. are subject to sales tax

Arizona (AZ),Colorado (CO),Connecticut (CT),District of Columbia (DC),Florida (FL),Georgia (GA),Illinois (IL),Indiana (IN),Iowa (IA),Kansas (KS),Kentucky (KY),Louisiana (LA),Maine (ME),Maryland (MD),Massachusetts (MA),Michigan (MI),Minnesota (MN),Nebraska (NE),Nevada (NV),New Jersey (NJ),New Mexico (NM),New York (NY),North Carolina (NC),North Dakota (ND),Ohio (OH),Pennsylvania (PA),South Carolina (SC),Tennessee (TN),Texas (TX),Utah (UT),Virginia (VA),Washington (WA),Wisconsin (WI) State and local tax laws are constantly changing. As tax laws continue to evolve, these jurisdictions are subject to change.

Value-added tax (VAT)

For international customers, Mapbox will charge value-added tax (VAT) on products and services where applicable.

Add or update tax information

To add or update your VAT ID, login to your account at and use the VAT Tax ID field. The number entered here will be added to your monthly invoices.

Request an exemption

If you are a tax-exempt customer, contact the Mapbox Accounts Receivable team ( to provide your sales tax exemption certificate.

Request a sales tax refund

Sales tax is generally applied to all invoices with taxable products where valid exemption documentation hasn’t been provided to Mapbox. If sales tax has been applied to your invoice, but you can provide valid exemption documentation covering the purchase period, you can get a refund on the sales tax portion of your payment if you contact within 30 days of the invoice date. After 30 days from the invoice date, you will need to contact your local state tax authority to process a refund.


Payment setting

Automatic payments

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

Public beta

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.

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 a 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, 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 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, reach out to our support team.

Billing emails

We will send the following billing emails to the profile email address registered under the account's main settings, even if the account is enrolled in the Monthly Invoicing beta.

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.

Updated payment information

Email subject: [Mapbox Billing] Your payment info has been updated

Mapbox sends a notification when the account's payment method is updated.

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

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