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.