Metering
Recording usage so it can be rated, and why the idempotency key is required.
Record after the work, not before
await base316.events.record({
externalId: "acct_1234",
event: "api_call",
idempotencyKey: requestId,
payload: { tokens: 1_420 },
occurredAt: new Date(), // optional; defaults to now
});Check before, record after. Work that failed should cost nothing.
The idempotency key is required
Not optional. A retry after a network timeout must not bill the same work twice, and Base316 cannot tell a retry from a second genuine call — only you know what "the same work" means.
A request id is usually right. The same key records the event once, however many times you send it, so a client that retries on timeout is safe by construction.
Meters aggregate events
A meter declares which event feeds it, which property of the payload carries the value, and how values combine:
| Aggregation | Use for |
|---|---|
COUNT | How many times something happened |
SUM | Adding a value up — tokens, bytes, minutes |
MAX | The peak within a period |
LAST | The most recent value — seats, active users |
SUM over payload.tokens is the common shape for AI products.
Periods
Usage is measured over the subscription's current billing period. Invoicing rates what was consumed in the period that just closed, so the clock that matters is the subscription's, not the calendar's.
Usage is billed in arrears — it can only be rated once it has happened. The recurring fee is billed in advance, because it pays for access about to begin. A renewal invoice carries both: last period's usage and next period's fee.
Credits
Prepaid credits extend a feature's allowance:
allowance = limit + creditsThey are drawn down as usage is metered, and the original grant is kept alongside what has been consumed so a balance stays explainable after it has been partly spent. A grant can be voided, which takes its remaining balance back immediately.
What this is not
Base316 is not an event store. Events are metered and rated, then aggregated — they are not queryable as analytics, and they are not a log. Keep your own record of anything you need to ask questions about later.