Usage Records enable you to tell Sphere how much a customer is using your products, so that way we can appropriately bill them for a metered subscription.
If you are billing your customers for a subscription based upon usage (e.g., metered billing), then you will need to keep track of your customer's usage on your backend, and submit those records to Sphere at the end of each billing cycle so that we can appropriately bill them.
The usageRecord object is how this communication occurs. You should create a usageRecord object at the end of each customer's current billing period for a metered subscription. Sphere will then attempt to bill that customer based upon the usage that you submit.
The usage record object
Let's take a look at a full usageRecord object:
{
"id": "usageRecord_27b8afdd5ef145bf9f15a87753c253be",
"quantity": 100,
"subscriptionItem": "subscriptionItem_a1430dbc962040bcbb56cbf8272a9b6e",
"timestamp": "1779642251",
"updated": "2021-01-01T00:00:00.000Z",
"created": "2021-01-01T00:00:00.000Z",
}
id: string Unique identifier for the object. Auto-generated by Sphere upon creation.
quantity: number The number of units that were used by the customer, up to this date.
subscriptionItem: string The id for the subscription that this usage record corresponds to.
timestamp: string Records the time for this usage quantity. Measured in seconds since the Unix epoch.
updated: string datetime for when the usage record was last updated.
created: string datetime for when the usage record was created.