Usage billing

A metered price charges for usage instead of a fixed quantity: API calls, tokens, active seats at their peak, or a percentage of the payment volume a customer processes. Your integration records usage events as the usage happens. At the end of each billing period, the renewal invoice bills the period's usage, with tax computed at that time.

This is billing in arrears. Prepaid usage, where customers buy credits first and usage draws them down, works through wallets and leases instead. One customer can have both, on different meters: a meter that a metered price bills can't also be paid from a wallet. Prepaid usage shows in the same usage lists and daily aggregates, with what it cost (amount, and amounts per currency on aggregates).

Meters#

A meter is a name for one kind of usage, such as api.calls or payments.volume: lowercase words separated by dots. A meter exists as soon as a metered price names it. Usage events name the meter they count toward.

Every metered price of a meter in a brand and mode describes the meter the same way:

• its aggregation: how a period's usage becomes one quantity. sum adds every event's quantity (API calls, volume). max takes the largest value (peak seats, storage). last takes the value of the event that happened last (a gauge such as active projects); two events at the same instant are ordered by their event ID;
• its pricing: per_unit charges the price's unit amount, or its tiers, per unit of usage. percent_of_amount reads the quantity as an amount in micros of the price's currency and charges a rate in parts per million: 0.4% is 4000.

Prices of one meter can differ in everything else: the interval, the unit amount or tiers, the currency of per-unit prices, and the per-period terms below. Percent-of-amount prices of one meter use one currency, because their quantities are amounts of it.

Metered prices#

A metered price is a recurring price with usageType: metered and recurring.metered terms:

Unit prices can be finer than the currency's smallest unit, such as €0.002 per call, because the invoice line is rounded once. Tiered metered prices work like tiered licensed prices, applied to the period's usage. Like every price, a metered price can't change what it charges once it's used; create a new one instead.

Recording usage#

Send usage with POST /api/v1/usage_events, in batches of up to 1,000 events. Each event has:

• customerId and meter;
• quantity: a whole number as a string. It may be negative: a refund that reduces processed volume is a negative event. A period whose usage adds up to less than zero bills nothing, and the difference becomes customer credit that reduces later invoices;
• occurredAt: when the usage happened, at most 5 minutes ahead of Ownrecord's clock and at most three years back;
• idempotencyKey: your own unique ID for the event, such as a request ID;
• optional attributes, such as { "model": "large" }, to see usage split by dimension.

Every event is counted once. If you send an event again with the same idempotency key, it's reported as a duplicate and not counted again, so you can safely resend a whole batch after a timeout. An event with a key that was already used for different content is refused.

The response has one result per event, in the order you sent them: created, duplicate or failed with an error. Valid events are recorded even when others in the batch fail. Events fail one by one when the customer doesn't exist or was deleted, when no metered price uses the meter (so a misspelled meter is caught instead of going unbilled), or when occurredAt is out of range. A request that is malformed as a whole, such as a quantity that isn't a whole number, records nothing.

Use an API key with the usage:write scope for the integration that records usage. Each request counts once against the key's rate limit, whatever the number of events in it.

Daily aggregates#

Ownrecord aggregates usage as it arrives, per customer, meter, day and set of attributes. A day is a calendar day in the legal entity's time zone, so a day around a daylight-saving change can be 23 or 25 hours long. Each daily aggregate has the day's total, its number of events, its largest quantity and its last event.

List them with GET /api/v1/usage_aggregates, filtered by customerId, meter and a range of days (from, to). The console shows the same figures on each customer's page, under Usage. GET /api/v1/usage_events lists the events themselves.

Billing periods and late usage#

At the end of a billing period, the renewal reads the period's usage exactly, from the instant the period starts to the instant it ends, even when those fall in the middle of a day. It prices the quantity with the metered price and adds the line to the invoice.

Usage can arrive after its period was invoiced: a delayed batch, or a refund recorded a few days later. Such an event is late. It's recorded and marked late, and the next invoice bills it as a separate late usage line: the difference between what the period costs with the late events and what it was billed. If the difference is negative, it becomes customer credit.

In test mode#

Test and live mode have separate usage, meters and prices. Usage recorded in test mode is never billed to anyone. Ownrecord's own volume pricing uses the same metered prices and usage events, with live volume only.