Skip to main content
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_id must match the subscription’s customer — otherwise 400
This prevents usage from being recorded (accidentally or maliciously) against another tenant’s or another customer’s subscription.

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

Authorization
string
header
required

Tenant API key obtained from POST /auth/register or POST /v1/developer/keys.

Body

application/json
subscription_id
string<uuid>
required
customer_id
string<uuid>
required
dimension
string
required
Example:

"api_calls"

quantity
integer<int64>
required
properties
object

Optional free-form attributes (max 20; keys ≤100 chars, values ≤255). The unique billable-metric aggregation counts distinct values of one property.

transaction_id
string

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: 255
dynamic_amount
integer<int64>

Optional 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.

Response

Event recorded.

status
string
Allowed value: "recorded"
event_id
string<uuid>