Blog
/
Guides

Usage-based API billing: how it works and how to build it

Usage-based API billing explained: metering, rating, and invoicing, pricing structures, prepaid vs. postpaid, a worked bill example, and how to build it.

Sara NelissenSara Nelissen
Written by
Sara Nelissen
Last updated
July 6, 2026
read time
6
minutes
Usage-based API billing explained: metering, rating, and invoicing, pricing structures, prepaid vs. postpaid, a worked bill example, and how to build it.

Table of contents

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.

What is usage-based API billing?

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:

  • API calls or requests
  • Tokens processed by a model
  • Compute seconds or GPU minutes
  • Data volume, like gigabytes transferred or records enriched
  • Outcomes, like a document processed or a task completed

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.

How usage-based API billing works

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

Event emission

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

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

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

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.

Usage-based API pricing structures

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.

  • Pay-as-you-go: a flat price per unit, such as $0.002 per call, with no commitment. Simple to explain and simple to start with, which is why so many developer APIs launch this way. More in the pay-as-you-go pricing guide.
  • Tiered or volume pricing: the unit price drops as usage grows, either per band (tiered) or for all units once a threshold is crossed (volume). The difference is subtle and changes the bill a lot, which the tiered vs. volume pricing breakdown walks through.
  • Subscription with overage: a monthly fee includes an allowance, and usage past it is charged per unit. Buyers get a predictable floor, and you get upside on heavy users, the setup behind most hybrid billing.
  • Prepaid credits or commitments: customers pay up front for credits or a committed spend and draw it down as they use the API. Common for AI APIs, where a credit can absorb different costs per model.

The API monetization models guide covers the full list, including freemium, outcome-based, and revenue share.

Prepaid vs. postpaid API billing

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.

Usage-based API billing example

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:

  • Base fee: $49.00
  • Included calls: 100,000 (covered by the base fee)
  • Overage: 340,000 − 100,000 = 240,000 extra calls
  • Overage charge: 240,000 ÷ 1,000 × $0.40 = $96.00
  • Total: $49.00 + $96.00 = $145.00

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.

How to implement usage-based API billing

To implement usage-based API billing, pick a value metric, track usage, rate it, bill the customer, and enforce limits in the request path.

1. Pick the value metric

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.

2. Track usage

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.

3. Rate usage

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.

4. Bill the customer

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.

5. Enforce limits in the request path

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.

Pros and cons of usage-based API billing

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.

Pros:

  • Price matches value: customers pay for what they use, which is easy to justify.
  • Lower barrier to entry: developers can start small without committing to a plan.
  • Revenue grows with the customer: expansion happens as usage grows, with no upsell conversation needed.
  • Costs and revenue move together: especially useful for AI APIs, where each call carries real compute cost.

Cons:

  • Less predictable revenue: monthly revenue swings with customer usage, which makes forecasting harder.
  • Bill shock: customers who can't see usage in real time get surprised, and surprised customers dispute invoices.
  • Gradual churn: customers often reduce usage gradually before they leave, which is harder to spot than a cancellation.
  • Heavier infrastructure: accurate metering, rating, and enforcement are real engineering work.

How to reduce the risks

  • Add a base fee: a subscription with included usage gives you a revenue floor and gives customers a predictable minimum.
  • Send spend alerts: notify customers at thresholds like 50%, 80%, and 100% of their allowance or budget.
  • Offer hard caps: let customers set a ceiling that blocks usage, which finance teams love.
  • Sell commitments to enterprise accounts: prepaid or committed spend with discounted rates smooths revenue for both sides.
  • Watch usage trends: a steady decline in calls is an early churn signal worth a conversation.

Where AI credits fit in usage-based API billing

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:

  • An append-only ledger: every grant, deduction, and expiry recorded as its own entry, which also gives finance an audit trail for revenue recognition.
  • Grants with their own rules: each grant carries an expiry, cost basis, category (paid or promotional), and priority.
  • A defined burn order: Stigg's consumption logic applies priority first, then the soonest expiry, then promotional before paid, and a single event can spill across several grants.
  • A rule for zero: a hard limit denies access, while a soft limit lets usage continue as an overdraft that the next grant settles.
  • Cost estimates before expensive calls: some teams reserve an estimated amount before a long workflow and settle the difference after, and Stigg's API can estimate an event's credit cost without ingesting it.

The AI credits guide covers how credit systems are built, and the credit pricing guide covers how to set the rates.

What to look for in usage-based billing software

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:

  • Metering accuracy: idempotent ingestion, deduplication, and late-event handling, so every call is counted once.
  • Scale and latency: ingestion that keeps up with your peak traffic, and limit checks fast enough to run on every request.
  • Flexible pricing: tiers, volume pricing, allowances, overage, credits, and per-model rates without custom code.
  • Invoicing: integration with your billing provider for invoices, tax, and collection.
  • Customer-facing usage visibility: dashboards or APIs where developers can check usage and spend.
  • Analytics: usage trends by customer, plan, and feature to feed pricing decisions.
  • Access control and enforcement: entitlements, caps, and budgets checked before the request runs.
  • Data residency options: for some enterprise buyers, metering has to run inside their own cloud.

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.

Build vs. buy for usage-based API billing

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.

Make every API call billable and enforceable with Stigg

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:

  • Ingest usage events with built-in idempotency, in batches of up to 1,000, from any number of services
  • Run BYOC metering inside their own VPC at 1M+ events per second with no per-event cost
  • Check entitlements and credit balances before the call runs, from a Sidecar that answers from an in-memory cache and falls back to configured defaults if the Edge API times out
  • Track credits in an append-only ledger with expiry, cost basis, category, and burn priority per grant
  • Set hard or soft limits per plan, plus budgets at the organization, team, user, and agent level
  • Keep invoices, tax, and payment collection in Stripe, Zuora, Airwallex, or another provider

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.

Frequently asked questions

What does API usage billing mean?

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.

What is API-based billing?

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.

What is usage-based billing?

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.

What is consumption-based billing?

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.

Can I bill customers based on usage?

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.

What is the difference between usage-based billing and credit-based billing?

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.

Latest news.

One email per month.
From engineers, for engineers.

Thank you! Your submission has been received.
Oops! Something went wrong while submitting the form.