Metered subscriptions are the type of subscriptions that run on a consumption-based usage, rather than license based.
To support this type of subscriptions, the billable quantity is based on the actual running consumption that each customer uses. This consumption needs to be reported.
After the consumption is reported (submitted), the billing can be calculated. The billing for consumption type subscriptions typically happens in arrears, for the used consumption for the past billing period.
This guide explains how to create a system to submit each customer’s consumption automatically. Once the consumption is submitted, the billing will be calculated automatically based on that, on the billing day.
Submitting the consumption in bulk via api
Consumption can be submitted in bulk for metered products or add-ons which will be used for billing. Two API’s are used to submit consumption. The POST allows for submission of consumption and the GET to query the status of the submission. The POST request returns a taskId which is used to query the status in the GET request. The GET API URL including the taskId can also be retrieved in the header of the POST request.
It is important to note that:
- If one consumption record submitted is not successful, all consumption records will not be saved.
- This means that another submission of bulk consumption records will have to be done once the failed error records have been corrected.
| Interaction # | Description |
| 1 | A bulk consumption request is sent to Cloudmore via POST request. |
| 2 | Cloudmore acknowledges the request and returns a response with task ID (status code 202). |
| 3 | A check is done to get the status using GET request with the task ID. |
| 4 | Cloudmore responds with status 200 and a message. |
| 5 | If the message=Processing |
| 6 & 7 | Continues to poll for status updates. |
| 8 | If the message=Successful |
| 9 | Bulk consumption lines have successfully been submitted. |
| 10 | If the message=Failed |
| 11 | Bulk consumption lines have not been successfully submitted. The response will contain failed consumption records with an error message for each failed consumption record. |
api endpoint details
Submit Consumption: Submit seller service consumptions in bulk
| Endpoint | /api/sellers/{sellerId}/services/bulkconsumptions |
| HTTP Method | POST |
| Request Body | { “consumptionRecords”: [ { “subscriptionId”: “232adf3b-1552-4bf8-afee-4d2e9cafa4f0”, “isAddon”: false, “quantity”: 100 }, { “subscriptionId”: “f2fcabd7-8a09-47ea-8e76-c73bf71c6887”, “isAddon”: true, “addOnId”: “8fada2a6-3c13-4fa8-b2c4-346a12996ed7”, “quantity”: 200 } ] } |
| Successful Example Response | 202 { “message”: “Task has been accepted and queued for processing.”, “taskId”: “fe82bad2-90ad-4025-b070-6119d4ccb274” } |
Query consumption status: Query status of the bulk submitted consumptions
| Endpoint | /api/sellers/{sellerId}/services/bulkconsumptions/{taskId} |
| HTTP Method | GET |
| Request Body | Successful { “message”: “Successful”, “failedConsumptionRecords”: [] } Failure { “message”: “Failed”, “failedConsumptionRecords”: [ { “errorMessage”: “Subscription e849c1c1-9094-4f1f-8ba5-f7d8620db8c1 does not exist for seller b637329d-b718-4e38-9056-5128e06321ea”, “consumptionId”: null, “subscriptionId”: “e849c1c1-9094-4f1f-8ba5-f7d8620db8c1”, “isAddon”: false, “addonId”: null, “quantity”: 400.0 }, { “errorMessage”: “Subscription feb5ca7a-ee56-49a4-bcde-cdc3048b8f9b does not exist for seller b637329d-b718-4e38-9056-5128e06321ea”, “consumptionId”: null, “subscriptionId”: “feb5ca7a-ee56-49a4-bcde-cdc3048b8f9b”, “isAddon”: true, “addonId”: “582f829a-2034-4906-b69e-123d398e364f”, “quantity”: 600.0 } ] } |
| Successful Example Response | 200 |
api field definitions
Submit Seller Bulk Consumption
| Field | Description |
| Request | |
| consumptionId | The unique identifier (GUID) of the consumption record. This property should be empty for new consumption records. |
| subscriptionId* | The unique identifier (GUID) of the subscription. |
| isAddon* | A boolean value to indicate whether the consumption record is for an addon. If set to true then an addonId must be provided. |
| addonId | The addon ID if the consumption record is for an addon. If an addon ID is provided, then isAddon must be set to true |
| quantity* | The quantity to be submitted for the subscription. |
| Response | |
| message | A message indicating whether the consumption records have been queued for processing or not. |
| taskId | The taskId that can be used to query the status of the submission GET /api/sellers/{sellerId}/services/bulkconsumptions/{taskId} |
Query Seller Consumption
| Field | Description |
| Response | |
| message | The status of the bulk consumption: Queued Records have been received and are awaiting processing. Processing Records are actively being processed. Failed An error occurred during processing. Refer to failedConsumptionRecords for further details. Successful Records have been processed successfully. |
| failedConsumptionRecords[].errorMessage | An error message indicating why the consumption record could not be submitted. |
| failedConsumptionRecords[].consumptionId | The unique identifier (GUID) of the consumption record. |
| failedConsumptionRecords[].subscriptionId | The The unique identifier (GUID) of the subscription. |
| failedConsumptionRecords[].isAddon | TIndicates whether the consumption record is for an addon. |
| failedConsumptionRecords[].addonId | Represents the ID of an addon if the consumption record pertains to an addon. |
| failedConsumptionRecords[].quantity | The quantity that was submitted. |
Other consumption endpoints
There are also some other endpoints that allow to submit consumption. However, these are older and not recommended. It’s recommended to migrate to the bulk submit consumption API endpoints above.
The followings API endpoints only allow for one subscription to be submitted at a time. The above bulk consumption API allows multiple subscription consumptions to be submitted in one API call and is the recommended API to use.
API Collection: SellerServiceConsumptions
| Operation | Swagger Description | Method | API |
| Return Seller Consumption | Returns all seller service consumption subscriptions | POST | /api/sellers/{sellerId}/services/consumptions |
| Submit Seller Consumption | Submit seller service consumptions | PUT | /api/sellers/{sellerId}/services/consumptions |
Note that it’s not recommended to use these endpoints anymore, as they only allow to submit consumption one-by-one for subscriptions. As your integration scales, the need to submit consumption in bulk increases.
When doing integrations, please implement the Submit Seller Bulk Consumption API endpoints instead. We are mainly supporting those.