In this guide, we will walk through how to load usage to a subscription using APIs.

Prerequisites

The subscription in Cacheflow must already exist.
The subscription must contain at least one usage product.

Get subscription details

The first step is to make a request to retrieve the subscription information, including the Billing Schedules that will be needed in order to load usage to the correct billing period.

Example GET /contracts/{id} request:

GET /api/latest/data/contracts/[id] HTTP/1.1
Host: [yourdomain].api.getcacheflow.com
Authorization: Bearer [Bearer Token]

Example response:

"billingSchedules": [  
 {  
 "id": "3bd40667-1767-42b8-96af-bd4b5b2ad06a",  
 "dueDate": "2022-08-31",  
 "amountDue": 300000,  
 "amountRemaining": 3300108,  
 "netDueDate": "2022-09-03",  
 "billingItems": [  
 {  
 "id": "a6bcaffc-84e7-4d90-9ea1-811b4bb9bff0",  
 "billingType": "product",  
 "cycleIndex": 0,  
 "cycleName": "2022-08-31",  
 "amountDue": 50000,  
 "contractItem": {  
 "referenceType": "contract",  
 "product": {  
   "id": "0387fd4e-f6dd-40b3-b63f-f26185717352",  
   "name": "API Calls",  
   "description": "Usage-based, stair-step pricing",  
   "recurrence": "recurring",  
   "pricing": "stairstep",  
   "consumption": "usage_based"  
  ...

The response will include an array of billingSchedules that represent each billing period for the subscription and an array of billingItems that represent each product the customer is subscribed to.

The billingItems.id is used to create/update the usage.

Create usage record(s)

Example POST /usage request:

POST /api/latest/usage HTTP/1.1
Host: [yourdomain].api.getcacheflow.com
Authorization: Bearer [Bearer Token]
Content-Type: application/json

[
  {
    "billingItemId": "a6bcaffc-84e7-4d90-9ea1-811b4bb9bff0",
    "quantity": 700000
  }
]

The response will include the updated amount based on pricing.

[  
 {  
 "id": "8f095e8b-7f55-4a3a-8e8b-ea1d62149932",  
 "billingItemId": "a6bcaffc-84e7-4d90-9ea1-811b4bb9bff0",  
 "productId": "0387fd4e-f6dd-40b3-b63f-f26185717352",  
 "quantity": 700000,  
 "amount": 2100000  
 }  
]