Usage
Record Usage Event
Record a metered usage event against a subscription dimension
POST
Record a usage event
Reports metered usage against a subscription dimension (e.g.
api_calls).
Events are aggregated at the end of each billing period and billed on the
next invoice for metered plans.
Request Body
The event timestamp is set server-side at ingestion time.
Ownership enforcement
The subscription is verified before the event is accepted:- the subscription must belong to the authenticated tenant — otherwise
404(also returned for subscriptions of other tenants, to avoid existence leaks) customer_idmust match the subscription’s customer — otherwise400
Example Request
Response
Errors
A replayed
transaction_id is not an error: it returns 200 with
"status": "duplicate". Errors use the standard envelope — see
Errors.
To read usage back, see Query Usage for
windowed buckets, Get Subscription Usage
for current-period totals with entitlement headroom, and
List Usage Dimensions for the dimension
catalog.
Authorizations
Tenant API key obtained from POST /auth/register or POST /v1/developer/keys.
Body
application/json
Example:
"api_calls"
Optional free-form attributes (max 20; keys ≤100 chars, values ≤255). The unique billable-metric aggregation counts distinct values of one property.
Optional idempotency key: a retried event with the same (subscription, transaction_id) collapses to the original (200 with status "duplicate" and the original event_id).
Maximum string length:
255Optional per-event exact price in minor units (non-negative). A dynamic charge bills the sum of these over the period; other charge models ignore it.
Record a usage event