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