Afternoon logoAfternoon

API usage billing: How to track calls and create invoices

Updated 2026-09-24

API usage billing turns customer activity into charges. A reliable process records a billable event, assigns it to a customer and period, applies the agreed price, then produces an invoice the customer can check.

Start with the billing rule, not the event pipeline. A request reaching your server does not always mean that the customer received a billable service. Retries, failed requests, streaming responses and included usage need explicit treatment.

Define what you bill

Write a short billing specification that answers these questions:

DecisionExample policy
Billable unitA successfully completed API request
CustomerThe account that owns the API key at the time of the request
Failed requestsNo charge for an internal server failure
RetriesCharge once for the same completed operation
Billing periodA stated timezone and start/end boundary
PriceThe customer's contract and price version in force at the event time
CorrectionsA linked adjustment with a reason, not a silent edit

These are sample choices, not rules every API must use. A compute service may bill for work performed even if the customer's job fails. Tell customers which costs they incur before they use the service.

For LLM products, decide whether you charge for input tokens, output tokens, cached inputs, a completed task or another unit. Keep those units separate in the usage record.

Choose the pricing model and calculation

ModelBilling rule to define
Pay as you goBillable quantity multiplied by the agreed unit rate
Graduated tiersUnits within each band multiplied by that band's rate
Volume tiersThe reached band's rate applied to the quantity specified in the contract
Minimum with overagesThe minimum, what it includes, and the charge above that allowance
Prepaid creditsThe purchase, eligible usage charges, and remaining balance
Different endpoint pricesThe endpoint or service class and its own billable unit and rate

Test the tier method with a worked case. At illustrative rates of $0.001 for the first million calls and $0.0008 above that, 1.5 million calls cost $1,400 under graduated pricing. If a volume contract instead applies $0.0008 to all 1.5 million calls, the bill is $1,200. The same rates and usage produce different totals.

Model the customer's charge and your delivery cost before changing prices. A lower rate for high usage can reduce margin if the underlying compute or third-party cost does not fall with it.

Record enough detail to explain a charge

A usage event should identify the event, customer, service, event time, quantity and unit. Keep the price version or enough contract history to determine it later.

An illustrative record could look like this:

{
  "event_id": "evt_example_001",
  "customer_id": "customer_example",
  "occurred_at": "2026-09-24T14:00:00Z",
  "service": "document_extract",
  "operation_id": "operation_example",
  "quantity": 1,
  "unit": "successful_request",
  "price_version": "standard_v1"
}

Treat customer identifiers and units as required fields. Reject or hold an event for review if you cannot map it to a customer or billable product. Do not assign it to a default account.

Store event time separately from arrival time. A request completed before the billing boundary can arrive in the billing system afterward.

Send billable events to durable storage and monitor gaps, rejected events, and processing delays. Keep a replay path after failures, with the same event identifiers so replay does not create extra charges. Compare source-system counts with accepted billing events; a pipeline that runs without errors can still miss usage.

Handle retries and late data

Use a stable identifier for the event you intend to charge. If delivery retries send the same event twice, the billing system should count it once.

That is different from deduplicating customer operations. Two event IDs can still describe the same retried operation. Your product needs a rule for when repeated API calls represent new work.

Before finalizing an invoice:

  1. Check that all expected event batches arrived.
  2. Resolve events with missing customer or product mappings.
  3. Apply the contract's cutoff policy.
  4. Calculate the charge from the retained event set.
  5. Preserve a version of the result for later review.

If usage arrives after finalization, use a documented adjustment or next-invoice policy. Do not rewrite a paid invoice without the appropriate correction record.

Turn usage into an invoice

The following example uses invented amounts only to show the calculation.

A customer's monthly plan includes 10,000 successful calls for $100. Additional calls cost $0.01 each. The customer makes 12,500 billable calls.

Invoice lineCalculationAmount
Monthly planIncludes the first 10,000 calls$100
Additional calls2,500 × $0.01$25
SubtotalBefore any applicable tax or credit$125

The usage report should explain the 12,500 calls. The invoice should explain why only 2,500 calls create an extra charge.

Do not use the same calculation for every tiered contract. Graduated pricing applies each tier's price to the units in that tier. Volume pricing applies the reached tier's price to the relevant total. The contract determines which method to use.

Show the billing period, units, price or calculation, included allowance, adjustments, tax and amount due. Link the invoice to a customer-readable usage breakdown. Use the B2B SaaS invoice template to present the charges, credits, and payment terms.

Add prepaid credits without double billing

If customers pay in advance, record the credit purchase separately from usage. Apply the agreed credit value to eligible charges and show the remaining balance.

A paid credit is a means of settling a charge. It is not automatically a discount. Keep promotional credits, purchased credits, refunds and invoice corrections distinct.

For the implementation details, see prepaid AI credits. For the terminology, see AI credits vs tokens.

Handle free usage, service credits, and foreign customers

Track included and free-tier usage even when it creates no extra charge. Keep it separate from paid overages so customers can check how much allowance remains. A paid plan's included usage is still part of the contract; “no extra charge” does not mean the plan has no revenue.

For a downtime credit, retain the affected service period, contractual basis, approval, and link to the original charge. Distinguish a price adjustment from a new cash-funded credit purchase. Have finance assess its effect on revenue and any remaining obligation; do not automatically recognize the face value again when the customer redeems it.

For foreign customers, agree on the invoice currency and check applicable tax and invoice rules. Keep transaction-currency amounts as well as their ledger values so settlement and exchange differences can be explained. The B2B invoicing guide covers the records to keep.

Choose a billing system against your actual contract

Evaluate a tool with a sample containing retries, late events, a price change, a credit and a refund. Check both the invoice and the exported records.

Current Stripe documentation distinguishes existing Billing Meters integrations from Metronome and recommends Metronome for new usage-based integrations. Do not start a new build from a legacy meter example without checking the current integration path.

Compare options in billing platforms for AI and API usage. Confirm which system owns metering, pricing, invoicing, payment collection and accounting.

Reconcile billing with revenue

An invoice is not a revenue-recognition policy. Your finance team must assess what the contract promises and when the business delivers it.

For a simple qualifying usage arrangement, usage can support the revenue calculation. Minimum commitments, prepaid rights, discounts and separate services may change the result. See usage-based revenue recognition.

At close, reconcile:

  • Usage records to the rated usage report.
  • Rated charges to invoices and adjustments.
  • Invoices to receivables and payments.
  • Purchased credit balances to the related accounting balances.

Investigate differences rather than forcing each report to equal the invoice total. A valid timing difference should have an explanation and a later settlement.

Run billing and close as a shared process

Give each stage an owner and a deadline:

  1. Engineering confirms that period usage is complete and resolves rejected events.
  2. Billing applies contract rates and reviews customers with unusual charges.
  3. Finance approves invoices, credit adjustments, and revenue entries under the contract policy.
  4. The team reconciles receivables, prepaid balances, and settlements, then records open exceptions.

Show customers their usage and provide alerts before large charges. State whether a budget control sends a warning or actually blocks further work, including any delay in enforcement.

Track billable usage, effective revenue per unit, revenue and delivery cost by plan, corrected invoices, disputed charges, collection status, and time to close. Review free-to-paid conversion and customer concentration where they affect planning. Pair changes in net dollar retention with usage changes so a temporary demand spike does not look like a contract expansion.

Review tax separately from billing

A usage invoice does not settle income-tax or sales-tax timing. Sellers should assess product taxability, customer location, registration duties, and any exemption support. See the SaaS sales tax guide.

Buyers should keep usage records and separate services already consumed from recoverable prepaid rights. The AI credit accounting guide shows the entries. Book and tax treatment can differ; IRS Publication 538 explains accounting methods and special rules.

Questions to settle before launch

Can I use access logs as billing records? Only if they capture the agreed billable events and survive retries, retention limits and corrections. Operational logs often lack that contract detail.

Should I send an event for every request? Use the integration's supported event model. Whatever its input format, keep enough evidence to reconstruct customer usage.

Can I bill transcription by API call? You can, but if the commercial unit is processed audio time, a call count does not measure the bill. Record the agreed duration unit and treatment of partial or failed jobs.