Usage
Usage is what a customer consumed: API calls made, gigabytes moved, messages sent. You record it as events; a meter turns those events into the number that appears on the invoice.
Only usage-based products need this. A flat fee or a per-seat product already knows its quantity.
Recording an event
One endpoint, POST /v1/usage-events. Six fields are required, and the sixth is
the one that matters most.
Code
quantity is a string and must be non-negative. timestamp is optional; omit
it and the event is stamped on arrival, which is what you want unless you are
backfilling.
Why the key is required
Usage ingest is the one endpoint you will call from a retry loop. A network timeout tells you nothing about whether the event landed, so retrying without a key double-bills the customer.
Make it deterministic from the thing being recorded, not random. A request ID, or
{subscription}-{metric}-{window}. The same key twice is recorded once.
Sending a batch
The same endpoint accepts a batch: a body with a non-empty events array is
processed as one. 1 to 1,000 events per call, verified in the request
validator.
Code
One cost currency per group in a batch
If your events carry external_cost_amount, every event sharing a
(subscription_id, metric_key) pair must use the same
external_cost_currency. Mixing them would sum raw numbers across currencies and
produce a wrong invoice, so the batch is rejected instead.
What the response means
| Status | Meaning |
|---|---|
201 | Recorded. The body is the created event, or the batch result |
202 | Queued. The event settles a wallet hold and is processed asynchronously; the body carries outcome_id |
409 | The idempotency_key was already used |
413 | The batch is over 1,000 events |
429 | Rate limited |
A 202 is not a failure and not a retry signal. It means the event names a
hold_id, so it is settling a reservation rather than being billed directly.
Keyed products
If the product is linked to a key set, every event must carry
price_key naming which variant was consumed. If it is not keyed, events must
not carry one. The two rules are symmetric and both are enforced.
Querying what was recorded
| Endpoint | Returns |
|---|---|
GET /v1/usage-events | The raw events, filterable |
GET /v1/usage-events/aggregate | The aggregated number a meter would produce |
The aggregate endpoint is the one to reach for when a customer asks why their bill says what it says: it answers with the same arithmetic billing used.
Where usage goes next
- Define a meter that aggregates these events, and bind it to the product. Until then, events are recorded and bill nothing.
- The invoice picks it up at the end of the period.
- Free allowances come from the plan's included quantity, or from a
usage_creditspromotion effect.
Next step
Continue to Meters to turn these events into a billable quantity.
Reference
| Topic | When you need it |
|---|---|
| Meters | Aggregation, windows, filters and deduplication |
| Products | Why a usage-based product needs a meter binding |
| Wallets | Holds, which are what a 202 is settling |
| Usage API | Every field on an event, and the aggregate query |