Documentation Get Support

API Billing & Subscriptions

We do not charge you for consuming your own API. Feel free to test as much as you like.

The API Billing Addon allows you to create recurring subscription plans for your API. These plans can be either simple or complex. For example, you can create plans like:

  • $29.99 Monthly Price
  • 100 Monthly Video Conversions
  • 200 Daily Image Conversions
  • Additional Video Conversions: $0.50/each
  • Additional Image Conversions: $0.25/each


The API Billing Addon is strongly integrated with Mashape. Some of the features include:

  • Simple & complex plans, including multi-custom objects support.
  • Subscribing / Unsubscribing to plans.
  • Downgrading / Upgrading subscriptions.
  • Billing information is securely stored in a PCI Data Security Standard (PCI-DSS) compliant system.
  • Automatic subscription suspensions and re-activations.
  • Life-time transaction retries for customer's debt collection.
  • Automatic email notification for critical subscription and credit card status changes.
  • Detailed invoice generation.


Only Mashape users are allowed to subscribe to billing plans. Thus, before consuming an API the user must have an account on Mashape. To authorize the users to consume the API and check if they're subscribed to a plan, the client must provide the authorization header using his Mashape Credentials and set them into the X-Mashape-Authorization header. If the user has provided the wrong credentials or it is not allowed to consume the API (i.e. he didn't subscribe to a plan), the request will be blocked by the proxy.


The API Billing Addon fee is 25%. For high-revenue APIs, custom terms can be privately agreed upon.


The API Billing Addon comes with a web administration console that allows you to easily create subscriptions and plans. For each plan you can set a monthly price and one or more daily or monthly limits, plus an additional price for each limit if the customer exceeds the allowed capacity.

Server-Side Configuration

A plan can have one or more limits. If this is the case, the Addon must be instructed by the API on how to increment/decrement the customer's specific counters for every request. This is done by providing a X-Mashape-Billing header from the server-side response. The header is of the form:

X-Mashape-Billing: [Limit1 Name] = [Value]; [Limit2 Name] = [Value]; [���]

For example, if you consider the following plan:

  • $49.99 Monthly Price
  • 100 Daily Video Conversions
  • 200 Daily Image Conversions
  • Additional Video Conversions: $0.50/each
  • Additional Image Conversions: $0.25/each

If your API exposes an endpoint that can convert more than one video or image per request (bulk image/video conversion), the API response generated by the server may include the following header:

X-Mashape-Billing: video conversions=3;image conversions=5

This instructs the addon to increase the consumed amount of video conversions by three units and the image conversions by five units for that customer. In the following plan, when the user has exceeded 100 daily video conversions, he is the billed $0.50 for every additional video conversion. The same is true for image conversions and any other limit you set.

You can also provide negative values to decrement the counter, like:

X-Mashape-Billing: video conversions=-1;

When a limit increase/decrease is not explicitly set in the header, it is ignored.

Auto-Increment without Server-Side configuration

If you don't want to change your server-side code, you can check an option to automatically increment a specific limit by one unit every time a request is made. This is extremely useful if, for example, you bill users on the number of queries made to your API, like:

  • $9.99 Monthly Price
  • 100 Daily Queries
  • Additional Queries: $0.05/each

If the option is checked, the Billing Addon will auto-increment the counter by one unit every time a user who is subscribed to that plan makes a request to the API. It is the equivalent of explicitly setting a server-side header like:

X-Mashape-Billing: queries=1

Needless to say, this feature could sometimes be harmful because it is automatically applied for every request without actually parsing the API response. This means that it may happen to automatically increment a limit even if the API request was not successful. The best practice is to always return a valued X-Mashape-Billing header.

Identifying the consumer and the plan

The proxy appends some custom headers that you can read server-side on your API to identify the user and the plan he's subscribed to.

Handshake flow between Mashape Billing and API provider