Subscription billing - the invoice is computed, not typed

Why this design

Every SaaS product, streaming service, gym and newspaper bills on a schedule, and the naive design - a cron job per customer that charges a stored amount - works until the first customer upgrades on the 17th. Interviewers ask this question to see whether you model the invoice as something computed from versioned prices and a period, whether you can do proration without floating point or double-counting a day, and whether you separate the invoice (a debt) from the charge (an attempt to settle it). Teams that run billing in production care most about the last part: failed payments, not plan design, decide how much revenue quietly walks away.

What you will learn

• Why a price is a versioned row that is never edited, and why an invoice references the version, not the plan name.
• Why the billing clock is a sweep over current_period_end <= now() with an idempotency key, rather than a scheduled job per subscription.
• How proration splits a period at the instant of a change, and the worked arithmetic of a $30 to $90 upgrade on day 10.
• Why an invoice is immutable once finalised, and corrections are credit notes.
• How dunning retries on a schedule, why a provider error must never enter dunning, and why the recovery rate is the most valuable number on the board.
• The honest weakness: a plan change racing a renewal at the boundary, and 1,050,000 renewals due in the same minute on the 1st.

How to read this board

1. Diagram, left to right: CHANGE (a customer edits the future), THE CLOCK (renewal is a query), COLLECTION (an invoice is a debt, a charge is an attempt), DUNNING (failure is the normal case). Press play for the walkthrough.
2. Below it, ACCESS: the only thing the customer actually feels.
3. Then the DATA MODEL: six tables. Look at what is unique on invoices.
4. Page 1 · Requirements, then Pages 2 and 3 · Capacity and Storage - 3.1 M renewals a month and why storage is not the problem.
5. Page 4 · Availability - what happens if the clock stops for six hours.
6. Page 5 · How it works - one upgrade and one renewal end to end, then Page 6 · Deployment, where a billing change is shadowed for a whole cycle.

A billing system turns a promise ("$30 a month for Pro") into a sequence of invoices and a sequence of attempts to collect them. It is not a payments system - it calls one - and it is not a pricing tool. Its job is to compute the right amount, for the right period, exactly once.

Ask these before designing

• Anchor on signup date, or on the 1st? Signup anchoring spreads renewals across the month. "Bill everyone on the 1st" is what finance asks for and it puts a third of the month into one minute.
• Proration on upgrade, on downgrade, or both? The common answer is: upgrade immediately and prorate, downgrade at period end with no credit. That asymmetry is a product decision that halves the proration code.
• Charge proration now or on the next invoice? Charging now means an extra card attempt (and an extra decline). Deferring means the next invoice carries pending items.
• Who owns tax? Sales tax and VAT depend on the customer’s location at the time of the invoice, not at signup. If tax is external, the invoice engine must call it inside finalisation.
• What does "past due" switch off? Read-only access, full suspension, or nothing for 14 days? This is the lever that decides whether dunning recovers 40% or 70%.

Functional

• Create, upgrade, downgrade, pause and cancel subscriptions; cancel at period end by default.
• At each period end, generate exactly one invoice per subscription per period.
• Prorate mid-period changes to the second, in integer minor units.
• Collect each invoice; on failure retry on a schedule and notify; suspend after the final retry.
• Issue credit notes; never edit a finalised invoice.
• Recompute any historical invoice from its inputs and get the same total.

Non-functional

• Exactly one invoice per (subscription, period), enforced by a unique key, not by the scheduler behaving.
• Renewal lateness under 5 minutes on a normal day; under 3 hours for collection on the 1st.
• Plan change p99 under 400 ms, including the proration preview.
• Never charge a card twice for one invoice, across retries, timeouts and provider redeliveries.
• Ten-year retention of invoices and lines - they are tax records.

Explicitly out of scope

Usage metering (it feeds this as line items), revenue recognition (it reads finalised invoices), the card network, and pricing experiments.