
Multi-Tenant Architecture: 3 Models & 8 Best Practices
Learn how multi-tenant architecture works, compare database isolation models, and explore six components & eight best practices for shared infrastructure.
Usage-based API billing explained: metering, rating, and invoicing, pricing structures, prepaid vs. postpaid, a worked bill example, and how to build it.
The first version of usage-based API billing at most companies is a cron job, a SQL query against the request logs, and a script that pushes line items to Stripe at the end of the month. It works, right up until a customer disputes an invoice and nobody can reproduce the number.
Usage billing for APIs looks simple from the outside, since you count calls and multiply by a price. In practice, the counting, the pricing rules, the invoice, and the limits that stop a runaway integration all live in different systems, and they drift apart under real traffic.
AI APIs raise the stakes, because an agent can burn through a month of usage overnight, long before an invoice catches it.
Stigg meters usage and enforces credits and limits in the request path for API and AI products, so we spend a lot of time on the parts of this stack that break first.
You'll get how usage-based API billing works end to end, the common pricing structures, prepaid vs. postpaid, a worked example bill, a step-by-step way to build it, the pros and cons, and what to look for if you'd rather buy than build.
Usage-based API billing is a pricing model where customers pay for how much they use an API, measured in units like calls, tokens, or compute time.
A flat subscription charges the same whether a customer makes ten calls or ten million, while usage billing scales the invoice with the work the API does.
The billing unit is whatever the product meters:
It's a big business. Postman's 2025 State of the API report found that 65% of organizations generate revenue from their API programs, and usage pricing is the natural fit for most of them because the cost to serve an API moves with volume.
That's especially true for AI APIs. The OpenAI API, for example, prices each model per million input and output tokens, because a flat fee would either subsidize heavy users or overcharge light ones.
The general model works the same way outside APIs, and the usage-based billing guide covers it in more depth. This article stays on the API side.
Usage-based API billing turns raw API activity into an invoice in four stages: event emission, metering, rating, and invoicing.
| Stage | What happens | Where it usually runs |
|---|---|---|
| Event emission | Each billable call produces a usage event | Your API or gateway |
| Metering | Events are aggregated per customer and period | A metering service |
| Rating | Pricing rules turn quantities into amounts | A rating engine |
| Invoicing | Amounts become invoice lines and get collected | A billing provider |
Every billable action produces a record with the customer ID, the feature or endpoint, the quantity, a timestamp, and an idempotency key. One model request might emit a single event with a token count, while a multi-step agent run emits several, each tied back to the session that started it.
Metering aggregates raw events into billable quantities, such as calls per customer per month or tokens per model per day. It has to count every event once, even when clients retry, which is why API metering depends on idempotency keys and deduplication.
Rating applies the price. Tiers, volume discounts, included allowances, contract rates, and per-model prices all resolve here, so two customers with the same usage can end up with different amounts.
Invoicing turns rated amounts into invoice lines, handles tax, and collects payment through a provider like Stripe or Zuora. It runs on settled data after the period closes, so it tells you what a customer owes after the fact, while the decision about their next request has to happen somewhere else.
Revenue recognition follows the same data. Postpaid usage is usually recognized in the period it happens, while prepaid credits sit on the books as deferred revenue and are recognized as customers draw them down, so finance needs the same usage records that produced the invoice.
The most common usage-based API pricing structures are pay-as-you-go, tiered or volume pricing, subscription with overage, and prepaid credits or commitments. Most APIs mix two of them.
The API monetization models guide covers the full list, including freemium, outcome-based, and revenue share.
Prepaid billing collects money before usage happens, while postpaid billing meters usage during the period and invoices it afterward.
| Dimension | Prepaid | Postpaid |
|---|---|---|
| When cash arrives | Before usage | After the period |
| Credit risk | Low | Higher |
| Developer friction | Has to buy credits first | Can start with a card on file |
| What enforcement needs | Real-time balance checks | Spend caps and alerts |
| Common in | AI APIs, credit packs | Usage APIs, enterprise contracts |
Prepaid moves the hard problem from collections to enforcement, since a balance has to be checked before each request and something has to happen at zero. Postpaid has the opposite problem, in that nothing stops usage by default, so a runaway integration shows up as a surprise invoice.
Plenty of API teams run both, with prepaid credits for self-serve developers and postpaid commitments with overage for enterprise accounts.
A usage-based API bill multiplies each customer's metered usage by the rate for that usage, then adds any fixed fees. Here's a worked example with illustrative numbers.
Say your plan is a $49 monthly base fee that includes 100,000 API calls, with extra calls billed at $0.40 per 1,000. A customer makes 340,000 calls this month:
Every number on that invoice depends on the stages above. If metering double-counts retries, the overage is wrong; if rating applies last month's rate, the total is wrong; and if the customer can't see their running usage, the $96 arrives as a surprise.
To implement usage-based API billing, pick a value metric, track usage, rate it, bill the customer, and enforce limits in the request path.
The value metric is the unit you charge for, and it should track what the customer gets and what it costs you to serve. Calls work for simple endpoints, while tokens, compute time, or completed tasks fit APIs where requests vary a lot in cost.
Pick something the customer can predict and see in their own logs, since a metric they can't estimate makes every invoice feel like a guess.
Emit a usage event for every billable action, with the customer ID, feature, quantity, timestamp, and an idempotency key. Retries are the classic trap, which is why APIs like Stripe's save the result of the first request for each idempotency key and return it for any retry.
Stigg's metering takes the same approach. Its metering docs describe built-in idempotency, so duplicate events are only counted once, batches of up to 1,000 events, and parallel reporting from distributed services.
Turn quantities into amounts with your pricing rules, such as included allowances, tiers, volume breaks, per-model prices, and any negotiated contract rates. Keep those rules in configuration, so a price change doesn't need a deploy.
Customers should be able to see their rated usage as it accrues, ideally in a dashboard or an API endpoint they can query, so the invoice confirms what they already expected.
Decide when you invoice (monthly in arrears, at thresholds, or up front for prepaid) and push the rated lines to your billing provider. Stripe, Zuora, and similar providers handle invoices, tax, and payment collection well, so there's rarely a reason to rebuild that part.
The four steps above all run after usage happens.
Holding a customer to a cap, protecting a prepaid balance, or keeping an enterprise team inside its budget takes a check before the request runs: does this customer's plan, balance, or budget allow this call right now?
The guide to API monetization covers real-time enforcement in more depth, and it’s the step most homegrown systems add last.
Usage-based API billing ties revenue to value and lowers the barrier to adoption, at the cost of less predictable revenue and more complex infrastructure.
AI credits are a prepaid form of usage-based API billing where each request draws down a balance that has to be checked before the request runs. That one difference changes the architecture.
Metered billing appends events and settles later. Credits make a decision against a live balance, so the system has to handle concurrency: two sessions read the same 200-credit balance, both claim 150, and both commit, leaving the wallet at −100 with no block triggered.
A production credit system usually needs:
The AI credits guide covers how credit systems are built, and the credit pricing guide covers how to set the rates.
Good usage-based billing software meters accurately, supports flexible pricing, generates invoices, shows customers their usage, and enforces limits in real time. Use this as a checklist:
The last two are where billing tools and enforcement layers usually split. Billing providers do invoicing well, and the real-time access decision tends to need its own layer.
Building usage-based API billing in-house works when usage is simple. One pricing model, one unit, modest volume, and postpaid invoicing can run on an events table, a nightly aggregation job, and a Stripe integration. Past that point, an API billing system also has to enforce limits in real time and keep an audit trail of every charge.
The build gets harder as requirements stack up:
| New requirement | What changes |
|---|---|
| Retries at scale | Idempotent ingestion |
| A second pricing model | Rating rules in configuration |
| Prepaid credits | A ledger with burn order |
| Concurrent sessions | Safe balance checks |
| Enterprise budgets | Limits per team, user, and agent |
| Finance audits | An immutable event history |
Each one tends to arrive from a different team (marketing wants promotional credits, product launches a second model, an enterprise deal needs team budgets), and together they turn a billing script into a system somebody owns full time.
Stigg's team wrote up what building AI credits took if you want to learn more.
Usage-based API billing works when the meter, the price, the invoice, and the limit all agree. Most teams already have invoicing handled in Stripe or Zuora, and the gaps show up in metering accuracy and in the check that runs before each call.
Stigg is the usage runtime for AI products. It meters usage, runs credits, and enforces entitlements and budgets in the request path, and it works alongside the billing provider you already use.
With Stigg, teams can:
If you're building API billing now and want a second opinion on the architecture, talk to a human at Stigg, or start with the AI quickstart in the docs.
API usage billing means charging customers based on how much they use an API, such as the number of calls, tokens, or compute time consumed in a billing period. The provider meters each request, applies a price, and invoices the total.
API-based billing usually refers to billing for API access by usage, where each call or unit has a price. It can also mean running billing operations through a provider's API, such as creating invoices or reporting usage programmatically.
Usage-based billing is a pricing model where customers pay for what they consume, so the bill rises and falls with usage. It's common for APIs, cloud infrastructure, and AI products, where cost to serve rises with usage.
Consumption-based billing is another name for usage-based billing. Customers pay for what they consume, such as API calls, tokens, or compute time, instead of a flat fee. The terms are used interchangeably, though “consumption-based” is more common in cloud infrastructure and enterprise contracts.
Yes, you can bill customers based on usage by metering each billable action, applying a price per unit, and invoicing the total through a billing provider. You'll also want spend alerts or caps so customers aren't surprised by the bill.
Usage-based billing measures consumption and usually settles it after the period ends. Credit-based billing is prepaid, so the available balance is checked before each request runs.