Recording usage

Report usage events, correct mistakes, and avoid double counting.

A usage event is one thing that happened: "100 API calls at 10:03." Your app reports these events against a metered subscription item as they occur, and the meter adds them up at the end of the period. Events are reported through the API, one at a time or in batches.

Reporting an event

Each event carries a quantity and when it happened. You post it to the usage-records endpoint:

POST /v1/usage-records for a single event.
POST /v1/usage-records/batch to send many at once.

See the API reference for the exact request shape of both. You can report events as they happen or buffer and send them later. Out-of-order arrival is fine, as long as the event still belongs to the open period. Each event says when it actually occurred, and that is what decides which period it belongs to.

Important

Report an event before its billing period closes. Once a period has rolled to the next one, an event dated back in the closed period is rejected, not quietly dropped, so the usage is not lost silently. If you buffer usage, flush it well before the period ends, and handle the rejection if one comes back. Events dated more than a few minutes in the future are rejected too, to catch a wrong clock.

Two timestamps

Every event has two times, and the difference matters:

When it happened. The real-world moment the usage occurred. This decides which billing period the event falls into.
When it was recorded. The moment yRecurring received it. This can be later, because reporting is often buffered or batched.

So an event that happened at 11:59pm on the last day of the month belongs to that month, even if your app does not send it until the next morning.

Correcting a mistake

Usage events are append-only. You never edit or delete an event you already sent.

Tip

To fix an overcount, post an offsetting event with a negative quantity: reported 50 by mistake, send a -50 to cancel it out. The two net to zero at roll-up, and the trail of what was reported stays intact.

This keeps a clean, permanent trail of what was reported and when, and it means the billing engine produces the same result every time it runs over the same events.

Avoiding double counting

Every event carries an idempotency key, a value you choose. It is required, because usage moves money and a retried request must not record the same usage twice. Send it in the request body or as the Idempotency-Key header.

If the same key is sent again with the same details, the second one returns the original event instead of recording a new one. If the same key comes back with different details, it is rejected as a conflict rather than silently overwriting the first event, so a bug that reuses a key does not hide changed data.

A batch can carry up to 1000 events in one call. Send more than that across several calls.

When it bills

Usage is billed in arrears, at the end of the period, because the total is not known until the period closes. At that point the meter rolls up the events, the number goes through the price, and the amount lands on the invoice. See in advance or in arrears for why usage is always billed after the fact.

Edge cases

Negative quantities are valid. They are how corrections work, not an error.
The event's own time picks the period, not when you sent it. Late reporting bills the right period as long as that period is still open; once it has closed, a back-dated event is rejected.
An idempotency key is required, and reusing it with different details is a conflict. A batch holds up to 1000 events.
For AI and cost-based billing, the event also carries a precise cost. Your app pushes the exact amount per event, and the meter sums those amounts. See dynamic pricing.