Customers can be charged based on how much of a feature they consume.

For example:

You sell a phone plan, and want to charge for how many texts your users send each month.


You need to add a usage pricing component to the rate plan you sell. Like all pricing components, this can be tiered. You can use price tiering to model "overage". For example, perhaps your rate plan includes 100 texts per month — but any consumption beyond this incurs a penalty:

0 -> 100    [$0.00/message]
101 -> ∞    [$0.05/message]

You could sell also a "BIG" plan where the customer gets more included texts than this. This is as simple as making that "free" tier wider.

Billing cycle

Every time a subscription enters a new billing period, an invoice (with type Subscription) is produced. In the case of a subscription to a "monthly" rate plan: you will enter a new billing period each month.


As you enter the billing period beginning 2015-09-10, an invoice is raised. The invoice is responsible for in-advance pricing components during 2015-09-10 until 2015-10-10. It is also responsible for any charges incurred in the previous billing period, 2015-08-10 until2015-09-10, that use retrospective pricing.

For example:

How much did the customer spend on texts this month? The final usage is know once the month finishes. Thus the consumption incurred in a given period can only be billed once we enter the period which follows it.

Note: An intra-month on-going cost calculation can be performed via a quote.

Quotes API documentation 

Billing retrospectively is called billing "in-arrears".

Example invoice

So, perhaps your pricing includes:

  • monthly fee of $5
  • usage-based fee for texts

Your monthly invoice could look like this:

Invoice generated on:

In-advance charges for period:
2015-09-10 until 2015-10-10

- $5 (monthly fee)

In-arrears charges from previous period:
2015-08-10 until 2015-09-10

- 101 text messages = $0.05
  - 100 text messages at $0.00/message
  - 1 text message at $0.05/message

Example Invoice

Alt : View sample invoice HTML.

Reporting Consumption

Let's get practical and work through an example of applying usage to an invoice; recall that:

Every time a subscription enters a new billing period, an invoice (with type Subscription) is produced.

Since your rate plan includes usage components, its invoiceIssueType will be set to Manual: any produced invoice will sit in the Pending state, waiting for you to perform further actions upon it.

A New Invoice Appears

By listening to webhook notifications, you can be informed of billing events. When any invoice is produced, a notification is raised with the domain Invoice and action Pending, (note: below entity property value unescaped for example):

   "id" : "NOT-A66C1042-83BC-4224-B197-D6D7BC37",
   "type" : "notification",
   "created" : "2015-10-02T12:24:10Z",
   "domain" : "Invoice",
   "action" : "Pending",
   "entityID" : "INV-C7D7BC92-11D1-4AC2-8DC5-78C53957",
   "entity" : {
       "type": "invoice",
       "id": "INV-C7D7BC92-11D1-4AC2-8DC5-78C53957",
       "subscriptionID": "SUB-926F46F4-CED2-475E-9E0E-8CF78A49",
       "accountID": "ACC-70CF7F1D-8703-4A3B-B9E2-21901467",
       "state": "Pending",
       "periodStart": "2015-12-02T12:18:51Z",
       "periodEnd": "2016-01-02T12:18:51Z",
       "currency": "USD",
       "invoiceCost": 5.00,
       "nonDiscountedCost": 5.00,
       "invoicePaid": 0

The above Invoice Pending notification is your cue to report consumption.


The invoice described in the notification's entity JSON is just a "lite" representation of that invoice. You can get more detail by fetching the invoice referred to in the notification's entityID

Step 1: Does Invoice have usage components?

Check that the Invoice's type is either Subscription (the monthly bill) or FinalArrears (the final bill upon cancellation). Both these types of invoice deserve to have usage reported to them. Fetching the invoice referred to in the notification's entityID will present you a detailed entity with no key clashes, so we recommend this approach instead of relying on the entity JSON in the notification.

Step 2: Confirm you have not yet applied usage

Check that the Invoice's versionNumber is 1 (i.e. it has never been recalculated). This is a clue that you have not yet reported consumption to it.

Step 3: Lookup usage charges for the Invoice

Given your Invoice's id, look up the charges associated with it.

Invoice Charges API documentation 

The response will look like this (abbreviated to highlight key data):

   "results" : [ {
      "id" : "CHG-BF467ABB-483B-46E8-B9A3-99587D48",
      "subscriptionID" : "SUB-926F46F4-CED2-475E-9E0E-8CF78A49",
      "invoiceID" : "INV-C7D7BC92-11D1-4AC2-8DC5-78C53957",
      "name" : "Monthly fee",
      "description" : "1 Recurring fees",
      "amount" : 5.00,
      "currency" : "USD",
      "periodStart" : "2015-12-02T12:18:51Z",
      "periodEnd" : "2016-01-02T12:18:51Z",
      "state" : "Pending",
      "pricingComponentName" : "Monthly fee",
      "productName" : "Standard membership",
      "productRatePlanName" : "Standard pricing (Monthly)",
      "pricingComponentValue" : 1,
      "pricingComponentType" : "subscription"
   }, {
      "id" : "CHG-8960CF32-A993-4EFA-8F48-26EB1F1A",
      "subscriptionID" : "SUB-926F46F4-CED2-475E-9E0E-8CF78A49",
      "invoiceID" : "INV-C7D7BC92-11D1-4AC2-8DC5-78C53957",
      "name" : "Text messages",
      "description" : "0 messages",
      "amount" : 0.00,
      "currency" : "USD",
      "periodStart" : "2015-11-02T12:18:51Z",
      "periodEnd" : "2015-12-02T12:18:51Z",
      "state" : "Pending",
      "pricingComponentName" : "Text messages",
      "productName" : "Standard membership",
      "productRatePlanName" : "Standard pricing (Monthly)",
      "pricingComponentValue" : 0,
      "pricingComponentType" : "usage"
   } ]

Find every charge where the pricingComponentType equalsusage. This should reveal the charge produced for "Text messages"!

Step 4: Calculate customer consumption

Recall the charge you just found for "Text messages". Notice that the charges declares their own period boundaries:

"periodStart" : "2015-11-02T12:18:51Z",
"periodEnd" : "2015-12-02T12:18:51Z",

And also it declares the name of the feature:

"pricingComponentName" : "Text messages"

Work out which feature in your system is meant by the name "Text messages", and count how much was consumed during the specified time interval. We recommend querying using intervals that are inclusive on exactly one end, so the next invoice you do will be back to back with this interval. e.g.: 2015-11-02T12:18:51Z <= TIME < 2015-12-02T12:18:51Z. Notice also the charge's id; you will need this for the next step:

"id" : "CHG-8960CF32-A993-4EFA-8F48-26EB1F1A",

Step 5: Recalculate the charge, informing how much was consumed

You must update the charge's pricingComponentValue. You can do this using the recalculate charge endpoint. Recalculating the charge will create a new version of the charge correctly calculating the price with regards to any tier or volume pricing that may exist.

Recalculate Charges API documentation 

Given the charge's id, you can issue a request such as:

curl "{charge-ID}/recalculate" \
    -H "Authorization: Bearer INSERT_ACCESS_TOKEN_HERE" \
    -H "Content-Type: application/json" \
    -X POST \
    -d \

And the API will respond with the recalculated charge:

    "id": "CHG-8960CF32-A993-4EFA-8F48-26EB1F1A",
    "accountID": "ACC-70CF7F1D-8703-4A3B-B9E2-21901467",
    "subscriptionID": "SUB-926F46F4-CED2-475E-9E0E-8CF78A49",
    "invoiceID" : "INV-C7D7BC92-11D1-4AC2-8DC5-78C53957",
    "name": "Text messages",
    "description": "105 messages",
    "amount": 0.1,
    "currency": "USD",
    "periodStart": "2015-11-02T12:18:51Z",
    "periodEnd": "2015-12-02T12:18:51Z",
    "state": "Pending",
    "pricingComponentName": "Text messages",
    "productName": "Standard membership",
    "productRatePlanName": "Standard pricing (Monthly)",
    "unitOfMeasureName": "Text messages",
    "pricingComponentValue": 105,
    "pricingComponentType": "usage"

Step 6: Recalculate the invoice

Once you have recalculated any usage charges you intend to deal with, your invoice needs to be recalculated with the new information. You can do this using the recalculate invoice endpoint. You can also issue the invoice to the customer during this step, by recalculating the invoice into the Unpaid state which will result in payment being taken for the invoice:

Recalculate Invoice API documentation 

Usage caps & measuring consumption

Your own system is responsible for watching how much of a feature the customer consumes, and stopping their use of the service once they reach some limit. Your system is also responsible for watching how much of a feature the customer consumes, and enabling them to view their consumption. The quote system can be used to give your customer a real-time view of their current on-going monthly costs, i.e. what their final monthly bill would be.

Quotes API documentation 


Structure and composition of charges