Retrieve a customer's usage
Early access. Not yet turned on for every account: until it is, this answers 404 not_found. Build against it now and ask us to turn it on.
Each meter’s usage for this customer over a half-open window
[start, end), computed from the events on read. Cancelled events
don’t count.
Without start and end, a meter that one of the customer’s live
subscriptions bills for reports over that subscription’s current
period, with estimatedAmount: what the usage so far would bill,
priced exactly as the invoice line will be. A meter that only a
limit entitlement watches (a free tier’s allowance) reports over the
limit’s period, the same count as the limit’s used. Any other meter
reports over the current calendar month in UTC. Each meter carries
the customer’s limit and remaining on it. With start or end,
every meter reports over that window, aggregate only.
Authorizations
Use a Bouclay secret key (sk_test_..., sk_live_...) or restricted key
(rk_test_..., rk_live_...).
A secret key can call every endpoint. A restricted key can only call the
endpoints its scopes cover. A scope is {resource}:{access}, for example
customers:read or refunds:write, and write includes read. GET
requests need read access and everything else needs write, except
POST /subscriptions/{id}/items/{item}/preview, which only needs
subscriptions:read. A request outside the key's scopes gets 403 permission_denied naming the missing scope, and its Idempotency-Key
is not used up.
Publishable keys (pk_...) are rejected by server-side API endpoints. A
key's mode scopes what it can see and charge: a test key can never reach
a live card.
Path Parameters
A Bouclay customer ID, or the externalRef you gave the customer.
Query Parameters
Start of the window, inclusive. Defaults to the first of this month, UTC.
End of the window, exclusive. Defaults to one month after start.
Only this meter, by ID or event name.