Skip to main content
GET
Get Usage
Returns the usage pricing, the merchant-approved cap and what has accrued in the current billing period — typically used to render a “used X of Y this month” bar in your app. Scope: read_billing. The installation is resolved from the access token. *Cents fields are minor units of the pricing currency (see Usage Records).

Response

string | null
Label of the metered unit, e.g. SMS.
number | null
Unit price in major units.
string
Pricing currency (ISO 4217).
integer | null
Merchant-approved cap (null when no cap is declared).
number
Usage recorded and not yet invoiced.
number | null
Headroom under the cap.
integer | null
A cap raise waiting for the merchant’s approval, else null.
string
active, trial, past_due, cancelled, …
string | null
End of the current subscription period.
boolean
true when the subscription is scheduled to end at currentPeriodEnd.
string | null
Metered subscription item the usage is reported on.
accruedAmountCents goes down by the invoiced usage when the period’s invoice is paid, so usage recorded after the period closed but before the invoice was paid is not lost.

Errors