Usage tracking via pending invoice

If you choose to track usage on an invoice after it is raised, this article will explain how

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.

Hint:

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 "https://api.billforward.net/v1/charges/{charge-ID}/recalculate" \
-H "Authorization: Bearer INSERT_ACCESS_TOKEN_HERE" \
-H "Content-Type: application/json" \
-X POST \
-d \
'{
"pricingComponentValue":105
}'

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