A meter counts something your customers use (API calls, seats, gigabytes) and bills it each period at a price per unit. Create meters on the Meters tab of Subscriptions in the dashboard, then send usage from your code. Usage is billed on top of a subscription plan's price (attach the meter to the plan), or to a customer each calendar month without a plan.
Meters & usage events APIEvery endpoint and field: record events one at a time or in batches, read usage.Recipe: report usageA complete usage reporter with safe retries and batching.
How usage is billed
- Your code sends an event for each thing used: the meter's
eventName, the customer, and avalue. - Events add up per customer and meter, the meter's way:
sumadds values,countcounts events,maxtakes the highest value,lastthe latest. - When a period closes (the subscription renews or ends, or the calendar month ends for a customer billed without a plan), the period's usage less the meter's included units is priced at the unit price.
- Each closed period becomes an invoice with one line per meter, charged to the customer's saved card. With no saved card, or if the card is declined, the invoice is emailed for them to pay.
Usage is matched to subscriptions and customers by email address, so a customer you name by id needs an email. A customer's usage on a meter is billed once: a period that has been billed is closed, and events stamped inside it are refused.
Sending usage well
- Give every event its own
idempotencyKey, such as your request id, so a retry after a timeout never counts twice. - Send events as they happen, or batch up to 100 a request. Each API key may make a set number of requests a minute (Rate limits), so batching is the way to send a lot.
- Timestamps may be up to five minutes ahead of our clock and at most 400 days old, and never inside a period already billed.
- Refusals come back with a code (
METER_NOT_FOUND,PERIOD_CLOSED,TIMESTAMP_TOO_OLD…): see Error codes.