API Usage-Based Billing Explained
Understand meters, events, aggregation, pricing, invoicing, and controls for reliable usage-based API billing.
Usage billing turns events into charges
A usage-based billing system records billable events, assigns them to a customer, aggregates them over a billing period, applies pricing rules, and produces an explainable charge. Each stage must be reproducible because customers will eventually ask why a number changed.
The API key often identifies the caller, but the bill should usually belong to a stable account or workspace. Keys rotate and projects change; billing history must remain attached to the customer entity even after a credential is revoked.
Define the meter before writing pricing code
A meter states exactly what is counted. Examples include successful requests, input tokens, generated seconds, rows processed, or gigabytes transferred. Define whether failed, cached, retried, and test requests count. Ambiguity here becomes a billing dispute later.
Store the raw event separately from the invoice summary. Raw events support audits and corrections; summaries make dashboards and invoices fast. Include an idempotency identifier so a retried ingestion request cannot bill the same event twice.
| Event field | Purpose | Example |
|---|---|---|
| event_id | Prevents duplicate billing | evt_01J... |
| account_id | Assigns the charge | workspace_42 |
| meter | Names the billable unit | output_tokens |
| quantity | Stores measured usage | 1840 |
| occurred_at | Places usage in a period | UTC timestamp |
Choose an aggregation and price rule
Most APIs sum usage during a billing period, but some products use maximum concurrent seats, high-water marks, unique resources, or graduated tiers. Write examples for values just below and just above every tier boundary. This catches pricing logic that appears correct at normal volumes but fails at edges.
Distinguish volume pricing from graduated pricing. Volume pricing applies one rate to all units after a threshold is reached. Graduated pricing applies each rate only to units inside its band. The invoice should make the chosen behavior obvious.
Give customers controls before invoices arrive
A dashboard should show current usage, included quota, estimated charge, rate limits, and recent events. Add threshold notifications and customer-controlled spending caps. A monthly invoice is too late to reveal that a leaked key or integration loop consumed the budget.
Usage data may arrive late or be corrected. Label estimates as estimates, show the last processed time, and define how late events are handled. For material corrections, keep an audit record rather than silently rewriting prior statements.
- Notify at several thresholds, such as 50%, 80%, and 100%.
- Allow limits at account, project, and API key level when practical.
- Return usage headers or a usage endpoint for automation.
- Document the timezone and exact billing-period boundary.
Reconcile usage, revenue, and provider cost
At the end of each period, reconcile your meter totals with provider invoices, internal logs, payment records, and customer statements. Differences can expose dropped events, duplicate ingestion, timezone errors, unbilled retries, or a unit conversion mistake.
Track revenue and provider cost by the same customer and product dimensions. This turns billing infrastructure into a margin system and makes the API Pricing Calculator more accurate than a company-wide average.