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:
| Decision | Example policy |
|---|---|
| Billable unit | A successfully completed API request |
| Customer | The account that owns the API key at the time of the request |
| Failed requests | No charge for an internal server failure |
| Retries | Charge once for the same completed operation |
| Billing period | A stated timezone and start/end boundary |
| Price | The customer's contract and price version in force at the event time |
| Corrections | A 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
| Model | Billing rule to define |
|---|---|
| Pay as you go | Billable quantity multiplied by the agreed unit rate |
| Graduated tiers | Units within each band multiplied by that band's rate |
| Volume tiers | The reached band's rate applied to the quantity specified in the contract |
| Minimum with overages | The minimum, what it includes, and the charge above that allowance |
| Prepaid credits | The purchase, eligible usage charges, and remaining balance |
| Different endpoint prices | The 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:
- Check that all expected event batches arrived.
- Resolve events with missing customer or product mappings.
- Apply the contract's cutoff policy.
- Calculate the charge from the retained event set.
- 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 line | Calculation | Amount |
|---|---|---|
| Monthly plan | Includes the first 10,000 calls | $100 |
| Additional calls | 2,500 × $0.01 | $25 |
| Subtotal | Before 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:
- Engineering confirms that period usage is complete and resolves rejected events.
- Billing applies contract rates and reviews customers with unusual charges.
- Finance approves invoices, credit adjustments, and revenue entries under the contract policy.
- 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.
Learn more about Afternoon
Seamlessly integrated financial stack, that handles your bookkeeping, taxes, and compliance.