Context
Usage-based products — including ones that meter LLM tokens — go wrong when a price change rewrites invoices that already shipped, or when the UI calculates money.
The Temporal Usage Billing & Entitlement Ledger keeps PostgreSQL authoritative for plans, receipts, ratings, invoices, credits, and ledger entries. Redis may cache an entitlement decision until it expires.
Decision
Prices are effective-dated with non-overlapping versions. Receipts are append-only, with duplicate, conflict, quarantine, and replay paths. A period will not close while accepted usage is unrated. Final invoices are immutable; late adjustments are forward-only. Ledger postings balance. Entitlement decisions are server-authoritative.
What I rejected
Updating the price row in place, and letting the client submit an amount. Both rewrite history or invent a charge the ledger never posted.
Failure scenario
Fifty concurrent deliveries of one receipt identity: one accept, forty-nine duplicates. A later price change creates a new version. Invoices already issued stay as they were; the next period rates under the new effective date.
Evidence
PostgreSQL ledger, reproducible invoice fixtures, and entitlement checks issued by the service. If an agent “checks remaining credits,” it should call this kind of API.
Inspect: Repository · Run locally