Most writing about usage-based pricing is about your vendor's meter - how to read GitHub's AI credits, why a Cursor bill jumped 25x, how to set a spend cap. This article is about the layer underneath: the database that actually records usage and turns it into an invoice line. If you are billing customers by usage, that store is the most load-bearing piece of your billing stack, and the default choice - a plain SQL usage_events table - quietly breaks in ways you only discover during a billing dispute.
UsageBox runs a purpose-built, append-only metering engine for exactly this reason. Here is what the job actually requires, and what a generic table gets wrong.
What a metering store has to guarantee
Billing accuracy is not a "nice to have" feature on top of storage - it is a set of hard invariants the storage layer has to hold, or the invoice is wrong:
- Idempotency. Every event carries a stable
event_id. A retried request with the same id is a duplicate, not new usage. Same id with a different payload is a conflict you want surfaced, not silently accepted. - Immutability. Raw usage is written once and never edited. That immutable record is the audit trail behind every invoice line - the thing you show a customer who disputes a charge.
- Cheap account-month totals. The number on the invoice ("2.4M units in June") has to be fast to compute without scanning millions of rows under a lock at billing time.
- Correctness under late data and corrections. Events arrive out of order; corrections land after you have already invoiced. The store has to give a stable invoice number while still tracking adjustments.
Why a plain SQL table betrays each one
The naive design is a table: (account_id, meter, quantity, ts), one row per event, SUM() at the end of the month. It looks fine in a demo and fails on each invariant in production.
Retries double-count
Usage collectors retry. Networks drop acks. Without a dedupe key enforced at write time, a retried batch inserts the same usage twice, and your customer is billed twice. Bolting on a unique constraint helps, but now you have to decide what a "conflict" means (same id, different quantity) - and a generic table has no opinion, so the bug stays silent until someone reconciles by hand.
Mutable rows destroy the audit trail
The moment usage rows can be UPDATEd - a backfill job, a "fix," a careless migration - you can no longer prove what a customer actually did. When they dispute a charge, "trust our current numbers" is not an answer. Corrections in a correct system are new, signed events that net against the original, never edits to history.
SUM-at-invoice-time does not scale
A SELECT SUM(quantity) ... GROUP BY over millions of rows at month-end is slow, contends with live ingestion, and gets slower every month. The fix is pre-aggregation (hourly or daily rollups) with raw events kept only as the correctness fallback - which is a second system you now have to keep consistent with the first. Get the consistency wrong and your fast number and your true number disagree, which is the worst possible bug in billing.
Late corrections after you have invoiced
You close June, send invoices, and on July 3 a corrected event for June 28 arrives. If your store has no concept of a closed period, that late event silently changes a number you already billed - so your records no longer match the invoice you sent. A correct store freezes a snapshot at close (the quantity, the event count, the watermark) and tracks later corrections as pending adjustments with a separate net total, so the original invoice stays stable and the adjustment is visible.
What a purpose-built metering store does instead
The design that actually holds the invariants looks less like a table and more like a small, opinionated database:
- Dedupe on ingest by stable
event_id, with same-id-different-payload flagged as a conflict (it usually means a buggy collector) rather than swallowed. - Append-only, immutable segments. Raw events are written once to compressed columnar files and never modified - that is the audit trail. A durable write path (write-ahead log, then sealed segments) means every acknowledged event survives a crash.
- Rollups as the fast path, raw as the truth. Background workers fold completed hours into rollups; the open hour falls back to raw. A built-in "verify" that compares raw against rollup catches drift before it reaches an invoice.
- Period lifecycle. Closing a month captures a frozen snapshot; corrections after close are accepted as adjustments and reported as
net_total = frozen + adjustments, so the invoice line is stable and auditable. - Corrections and retractions as first-class events - negative-quantity entries that net against the original, never edits to history.
Build vs. buy
You can build this. It is also a genuine database problem - durability, crash recovery, compaction, idempotency under retry, reconciliation - not a weekend table. That is the same realization driving the wave of metering acquisitions in 2026: Stripe bought Metronome, Adyen bought Orb, and Salesforce is buying m3ter. Metering is being recognized as strategic infrastructure precisely because it is hard to get right and expensive to get wrong.
The decision is not "table vs. nothing" - it is whether your invoices are idempotent, auditable, and reconcilable by construction, or only until the first dispute. UsageBox gives you that store without the build: stable-id dedupe, an immutable audit trail behind every line, rollups with raw-vs-rollup verification, and period close with frozen snapshots - and your data stays exportable, so you are never locked in.
Related reading: the meter as a management instrument and the usage-based billing guide.