Usage billing breaks in the seams between plans and periods: proration on a mid-cycle change, an upgrade charged from the wrong moment, a metering pipeline that drops an hour of events, a credit no one reverses. The durable fix is an event-sourced subscription timeline plus a reconciliation layer that ties billed quantity back to the source usage log before any invoice goes out.
The invoice itself is the easy part. Rate times quantity, sum the lines, apply tax. What makes subscription and usage billing hard is that quantity is a moving target and the plan under it changes on days that rarely line up with the billing period. Get the accounting of time and events wrong and you produce invoices that are individually plausible and collectively impossible to reconcile.
Proration breaks when the subscription forgets its history
Most billing bugs I see are not bad multiplication. They are lost history. A customer upgrades from the 50-seat plan to the 200-seat plan on the 14th, downgrades a metered add-on on the 22nd, and the billing system stores only the current state: 200 seats, add-on off. Now try to build a correct invoice for the month. You cannot, because the record you need was overwritten.
Model the subscription as an append-only timeline instead. Every plan change, quantity change, pause, and cancellation is a dated event, and the state at any instant is a fold over those events. Proration then falls out of the model:
- Each invoice line covers a specific interval
[start, end)at a specific rate, and the timeline tells you exactly where those intervals begin and end. - An upgrade splits the period into two lines with two rates, and the split date is a fact on record, not a value inferred at invoice time.
- Reversals and cancellations are new events, never edits to old ones, so a corrected invoice is reconstructable and the original is still there to audit.
This is also what makes point-in-time correctness achievable. When finance re-runs a billing period to investigate a discrepancy, they need the subscription state as it was known during that period, not as it is today. An event log gives you that for free. A mutable subscriptions table gives you a plausible answer that quietly contradicts the invoice you already sent, and you will not notice until quarter-end.
Reconcile billed quantity against source events before you invoice
Metered billing has a failure mode that flat subscriptions do not: the number you bill is computed from a pipeline, and pipelines drop events, double-count them on retries, and fall behind under load. Your product emits usage events. Those events flow through a collector, maybe a queue, maybe an aggregation job, and land in the billing platform as a metered quantity. Every hop can lose or double an event, and the customer only sees the total.
So the billed quantity is a claim, and it needs checking against the source of truth before the invoice is final. Build the reconciliation as a scheduled job that runs before the billing close:
- Pull the raw usage events from the product’s own log for the period, aggregated by customer and meter, with idempotency keys so a replayed event counts once.
- Pull the quantity the billing platform is about to charge for the same customer and meter.
- Diff them. A meter that matches to the cent needs no attention. A meter that is off by more than a tolerance you set goes to a review queue with the two totals and the delta.
The deltas cluster, and the clusters are diagnostic. A whole cohort short by a similar fraction usually means a metering outage in a time window; you can see the gap in the event timestamps. A single customer over by a round number usually means a duplicate emission from a client retry. Entity resolution shows up here too, because product usage is keyed on an account ID and billing is keyed on a customer or subscription ID, and the mapping between them drifts as accounts merge, split, and get re-parented. Keep that mapping as owned reference data with a maintainer. Teams that instead rediscover it as an ad-hoc join each run end up mis-attributing usage the moment two accounts merge.
The point of doing this before the invoice is that a wrong invoice you catch is a queue item, while a wrong invoice you send becomes a dispute and a credit, and it costs you standing with a customer who now double-checks every bill. Straight-through processing is the goal for the meters that reconcile clean. The false-positive budget is how you set the tolerance: too tight and every rounding difference floods the queue, too loose and real leakage slips through. Calibrate it against a few closed periods of real data rather than guessing.
Disputes and credits need a closed loop or revenue walks out
A dispute is not finished when you issue the credit. It is finished when the credit is either kept, because you were wrong, or reversed, because you were right and the customer paid. The gap between those two states is where revenue quietly disappears. A support agent issues a goodwill credit to end a call, the underlying reconciliation later shows the charge was correct, and nobody claws the credit back because no system was tracking the obligation.
Treat every credit as an open item with a lifecycle, the same way you would treat an open receivable:
- Record why the credit was issued and link it to the specific invoice lines and the metering delta in dispute.
- Keep it open until the reconciliation resolves, then either close it as accepted or generate the reversing charge.
- Report the aging of open credits, because a credit that has been open for two cycles is either a resolution you forgot to book or a control gap.
Everything above needs an audit trail that a controller can follow without asking an engineer. For any invoice line: which subscription events produced it, what rate and interval applied, what the source-event reconciliation showed, and whether a human overrode anything. Lineage from the number on the invoice back to the usage event is what lets revenue operations answer a customer’s dispute in minutes and close the period without a spreadsheet of unexplained variances. Without it, every billing question becomes an investigation, and the investigations pile up exactly when you have the least time for them.
FAQ
Why not just trust the billing platform's invoice totals?
The platform computes an invoice from the plan and the metered events it received, but it cannot tell you whether those events match your product's own usage records. Reconciliation between the source-of-truth event log and the billed quantity is what catches dropped events, double counts, and silent metering outages.
How do you handle a mid-cycle upgrade without a customer dispute?
Compute proration from an event-sourced subscription timeline, so every plan change is a dated record rather than an overwrite. The invoice line then shows the exact intervals and rates it charged, which is what lets a support agent explain a charge instead of arguing about it.
Where does most billing revenue leakage actually come from?
Usage that gets metered but never billed, and credits that get issued but never clawed back when the dispute is resolved in your favour. Both are reconciliation gaps, not pricing mistakes, and both are invisible until you tie billed quantity back to source events.