Skip to content

Metered Subscriptions Automation

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
1A bulk consumption request is sent to Cloudmore via POST request.
2Cloudmore acknowledges the request and returns a response with task ID (status code 202).
3A check is done to get the status using GET request with the task ID.
4Cloudmore responds with status 200 and a message.
5If the message=Processing
6 & 7Continues to poll for status updates.
8If the message=Successful
9Bulk consumption lines have successfully been submitted.
10If the message=Failed
11Bulk consumption lines have not been successfully submitted. The response will contain failed consumption records with an error message for each failed consumption record.
Interactions of the diagram above

api endpoint details

Submit Consumption: Submit seller service consumptions in bulk

Endpoint/api/sellers/{sellerId}/services/bulkconsumptions
HTTP MethodPOST
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 Response202

{
“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 MethodGET
Request BodySuccessful
{
“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 Response200

api field definitions

Submit Seller Bulk Consumption

FieldDescription
Request
consumptionIdThe 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.
addonIdThe 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
messageA message indicating whether the consumption records have been queued for processing or not.
taskIdThe taskId that can be used to query the status of the submission
GET /api/sellers/{sellerId}/services/bulkconsumptions/{taskId}

Query Seller Consumption

FieldDescription
Response
messageThe 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[].errorMessageAn error message indicating why the consumption record could not be submitted.
failedConsumptionRecords[].consumptionId
The unique identifier (GUID) of the consumption record.
failedConsumptionRecords[].subscriptionIdThe The unique identifier (GUID) of the subscription.
failedConsumptionRecords[].isAddonTIndicates whether the consumption record is for an addon.
failedConsumptionRecords[].addonIdRepresents the ID of an addon if the consumption record pertains to an addon.
failedConsumptionRecords[].quantityThe 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

OperationSwagger DescriptionMethodAPI
Return Seller ConsumptionReturns all seller service consumption subscriptionsPOST/api/sellers/{sellerId}/services/consumptions
Submit Seller ConsumptionSubmit seller service consumptionsPUT/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.