The short answer: A billing API for usage-based products has to do five things well, and most of the difficulty is in the first one. It must accept usage events idempotently, aggregate them correctly including late arrivals, expose a balance before the invoice exists, price that balance against a plan, and let you prove afterwards how any number was derived.
Anything that does the last two but not the first three is an invoicing API. That distinction is the whole reason usage billing projects run long.
Teams evaluating billing APIs usually start by comparing endpoints and SDKs. That is the wrong end. Every candidate has a create-invoice endpoint and none of them fail there. Projects fail at ingestion and reconciliation, so that is where the evaluation should start.
Here is the checklist we would use, in the order the requirements actually bite.
1. Idempotent ingestion
Your producers will send the same event more than once. Not might: will. Workers restart mid-flush, queues redeliver on visibility timeout, retries fire after a response was lost on the wire. If the API accumulates blindly, you bill a customer twice and they find it before you do.
What good looks like: every event carries a client-supplied idempotency key, the server deduplicates on it within a defined window, and re-sending an identical event is explicitly safe and documented as such. Ask what the deduplication window is, and what happens to a duplicate that arrives outside it, because "we deduplicate" without a stated window is not an answer.
2. Late and out-of-order events
Distributed producers do not deliver in order. An event timestamped 23:58 on the last day of the month can arrive at 00:03 the next day, after the period you would like to have closed.
The API needs a defined policy, not a surprise. Does it attribute by event timestamp or by arrival time? Is there a grace window before a period hardens? What happens to an event that arrives after close: rejected, attributed to the next period, or does it reopen the previous one and restate an invoice you already sent? Every option is defensible. Not knowing which one you bought is not.
3. A balance that exists before the invoice
Customers of consumption products expect to see spend accruing. The market has been trained by two years of bill shock stories to distrust anything invisible, and the expectation now extends to hard caps that actually stop work rather than alerts that arrive after the money is gone.
That requires continuous aggregation, not a period-end batch. Ask how fresh the balance is, whether the cap is enforced synchronously at the point of use or asynchronously after the fact, and what happens during a partial outage of the metering layer. A cap that fails open is a very different product from one that fails closed, and both are legitimate, but you should choose deliberately. We went through the design space in hard spend caps and usage kill switches.
4. Pricing that survives a pricing change
Every company selling AI has changed its pricing model at least once since 2024, most more than once. Tiers get restructured, a credit system appears, a model gets retired and its rate disappears.
The requirement is that historical periods keep pricing at the rates in effect at the time, while new periods use the new rates, without a migration script and without restating closed invoices. Ask directly how a mid-month price change is handled and whether closed periods are immutable. If the answer is that pricing lives in a config the system reads at compute time, closed invoices will silently change when the config does, which is the failure mode behind hardcoded pricing tables going stale.
5. Auditability
At some point a customer disputes a line, or finance asks why your pass-through revenue does not match the vendor bill. Answering means going from an invoice line back to the events that produced it.
Ask how long raw events are retained, whether they remain queryable rather than archived to cold storage, and whether you can export the exact event set behind a given aggregate. If the platform only keeps aggregates after a retention window, your future self cannot answer the question. Reconciliation against vendor bills is a whole discipline of its own, which we walked through in reconciling a vendor bill against your own meter.
The evaluation table
| Capability | The question to ask | Bad answer |
|---|---|---|
| Idempotency | What is the deduplication window and key? | "We handle retries" |
| Late events | Event time or arrival time, and what happens after close? | "That is unusual" |
| Live balance | How stale can the number be, and are caps synchronous? | "Available at period end" |
| Price changes | Are closed periods immutable? | "Pricing is in config" |
| Audit | Can I export the events behind this invoice line? | "We retain aggregates" |
Build versus buy, briefly
The five requirements above are the honest scope of building it yourself. None is exotic and all are solved problems, but together they are a system with correctness guarantees, not a table with a sum over it. The most common mistake is underestimating requirement two, because late and out-of-order events do not show up in development and appear for the first time at scale, at month end, in production.
If your usage is modest and your plan lifecycle simple, a subscription platform's metered billing will carry you further than people expect, and we drew that boundary in Chargebee metered billing for AI usage. If consumption is the business, the counting deserves a system designed for counting, whether you buy it or own it.
The honest take
Evaluate billing APIs from the ingestion end, not the invoice end. Ask the five questions above, in that order, and note which vendors answer with a specification versus which answer with a reassurance. The ones with a specification have thought about the failure modes you have not hit yet.
And whichever you pick, keep the raw events with their idempotency keys somewhere you can query. Every hard billing conversation, disputes, audits, vendor reconciliation, ends at the same place: show me the events. A system that cannot do that will cost you a week the first time somebody asks.