Retrieve Subscription Usage
Reads the metered usage a subscription has accrued in its current billing period, priced by the meters on its plan.
GET
Retrieve Subscription Usage
Returns the metered usage a subscription has accrued in its current billing period, priced by
the meters attached to its plan — one item per meter, with the aggregated quantity, the quantity
that is actually billable after any included credits are consumed, the unit price and the
resulting amount, plus a total for the period. This is a read: it does not itself trigger billing.
See Usage-Based Billing for how a
subscription accrues meters, credits and pricing in the first place.
Reading the response
Every quantity and amount is a JSON number.
A subscription with one metered item
When there is nothing to bill
A subscription whose plan has no meters, or that has no plan at all, returnsitems: [] and a
zero total rather than an error.
Reporting is asynchronous
POST /subscriptions/meters/events answers 202 once the event is validated, before it is
stored. A usage read that lands moments after reporting an event can still show the total from
before that event — a subscription’s items stayed at the same quantity and events_count on a
read taken immediately after a further event was reported on stg. Allow a short delay before
relying on a read to reflect the very latest report.