Subscription & Billing — Turning "Charge by Time and Usage" into an Auditable EngineLifecycle State Machine, Proration, Usage Metering, Multi-currency & Tax

Problem & Constraints

Design a SaaS billing platform (think Stripe Billing / Chargebee): 100K business subscriptions, hybrid pricing = monthly/annual fixed fee (seat-based) + usage-based charges (API calls, storage GB). Customers upgrade/downgrade and add/remove seats at any time, across 30+ countries, in multiple currencies, with automatic tax. This is the upstream of Day 17 payments: payments solve "how to safely collect a charge," billing solves "how much to collect this month, from whom, and why."

Key constraints to clarify in an interview:

• Always integer money: store minor units (cents), never float — rounding drift accumulates into reconciliation breaks.
• Explainable invoices: every line item must trace back to "why this amount" — regulators and customer disputes both demand it.
• Idempotent changes: a re-run billing cron or a double-clicked "upgrade" must not generate a second invoice.
• Scale: ~100K invoices/month for fixed fees, but ~1B usage events/day — the real throughput bottleneck is metering, not invoicing.
• Latency: invoice generation can be async (minutes), but proration preview must be sync (< 300ms) so the customer sees the delta on the spot.

High-level Architecture

Component roles: ① Pricing Catalog defines products, prices, plans (versioned, so price changes don't touch existing subscriptions); ② Subscription Service holds each subscription's lifecycle state machine; ③ Metering dedupes and aggregates massive usage events into billable quantities; ④ Billing Engine is the core — at cycle end it rolls "fixed fee + usage + proration adjustments + tax" into one invoice; ⑤ the invoice goes to Day 17's idempotent payment for collection, failures enter Dunning; ⑥ all amounts land in the Ledger for revenue recognition and reconciliation.

Key Technical Points

① Subscription Lifecycle State Machine + Cycle Trigger — bill on time, never miss, never double

Core trade-off: an explicit persisted state machine replaces if-else scattered everywhere and the risk of double-billing.

[Principle] A subscription isn't a boolean "active/inactive" but a state machine: trialing → active → past_due → canceled / unpaid. Transitions are driven by two event types: time (cycle end = time to invoice) and actions (upgrade, cancel, payment success/failure). On-time billing has two trigger styles: a scan cron (every minute query next_billing_at <= now) or a scheduled job registered per subscription. The key is idempotency: use (subscription_id, period_start) as a unique key for "generate invoice for period P," so a re-run cron only hits the existing invoice and never double-bills.

# pseudo-code: idempotent cycle billing (cron every minute)
def bill_due_subscriptions(now):
    for sub in db.query("status IN ('active','past_due') AND next_billing_at <= %s", now):
        period = (sub.current_period_start, sub.current_period_end)
        # unique-key dedup: one invoice per period
        inv = db.get_or_create_invoice(sub.id, period[0])
        if inv.status != 'draft':          # already issued -> skip
            continue
        add_recurring_lines(inv, sub)      # fixed fee / seats
        add_metered_lines(inv, sub, period)# usage (see point ③)
        finalize_and_charge(inv)           # finalize -> hand to payment
        sub.advance_period()               # advance to next cycle

② Proration — how to "settle the difference" on mid-cycle changes

Core trade-off: proration makes pricing fair and immediate, but every change injects a positive and negative adjustment line, raising complexity and explainability cost.

[Principle] A customer upgrading mid-cycle from $10/mo to $20/mo can't be charged a full month at the new price. Proration splits at the change point: refund the unused portion of the old plan's remaining time (negative credit), charge the new plan's remaining time (positive). Upgrade halfway through → -$5 (old price unused) + $10 (new price remaining) = net $5. These accumulate as invoice line items, settled next cycle or immediately. The proration factor = remaining seconds / total period seconds — computed by the second, not the day, or boundaries get unfair.

# pseudo-code: upgrade proration (by-second factor)
def prorate_change(sub, new_price, now):
    total = sub.period_end - sub.period_start      # total period seconds
    remain = sub.period_end - now                  # remaining seconds
    factor = remain / total
    credit = -round(sub.current_price * factor)    # refund old-price unused (minor units)
    charge =  round(new_price        * factor)     # charge new-price remaining
    add_line(sub.invoice, "unused time credit", credit)
    add_line(sub.invoice, "remaining time @ new", charge)
    sub.current_price = new_price                  # balance credit applied, no cash refund

③ Usage Metering — aggregating 1B events/day into a few numbers

Core trade-off: balance accuracy (count every event) against throughput/cost (aggregate then record), plus the risk of late events corrupting a finalized invoice.

[Principle] The metering pipeline has four stages: Emit (app sends usage events) → Ingest (validate + idempotent dedup) → Meter (aggregate into billable quantity) → Invoice (roll into the bill). Writing 1B/day one row at a time blows up the DB; the industrial approach is two-level aggregation: first accumulate in app memory/Redis keyed by (customer, meter, hour), flush to a Postgres rollup table every minute, and at billing time just SUM a few thousand hourly buckets. Aggregation functions are limited: typically only sum / count / last — for "peak concurrency" or "average daily storage" you compute it yourself and report the final number as a last value. Events must carry an idempotency key (event_id) for dedup, or client retries = over-billing.

# pseudo-code: two-level aggregation + idempotent dedup
def ingest(event):
    if not redis.set(f"seen:{event.id}", 1, nx=True, ex=DAY):  # idempotent
        return                                  # drop duplicate event
    key = (event.customer, event.meter, hour_bucket(event.ts))
    redis.hincrby("usage", key, event.qty)      # in-memory accumulate

def flush_every_minute():                        # level 2: to Postgres
    for key, qty in redis.hgetall("usage"):
        db.upsert_rollup(key, qty)               # hourly bucket
# billing: SELECT SUM(qty) ... WHERE customer=? AND ts IN [period]

④ Multi-currency & Tax — one engine serving the globe

Core trade-off: local-currency pricing gives the best experience, but introduces FX risk, tax-rule complexity, and a reconciliation-dimension explosion.

[Principle] Two things must be right. Currency: store each price in minor units + ISO currency code (JPY has no decimals, dinar has three — don't assume two); cross-currency do not convert at billing time but preset a price per currency, so FX swings don't make the invoice non-reproducible. Tax: whether tax is added on (exclusive, common in the US) or included (inclusive, EU VAT) is determined by region/currency; products carry a tax code deciding rate and exemption. Tax is frozen into the invoice at the rate in effect at billing time; later rate changes don't rewrite historical invoices.

Scaling & Optimization

• Billing spike: spread anchor dates across the whole month (not all on the 1st), shard the billing run across workers in parallel; compute usage rollups incrementally within the cycle so billing only does the finishing touches.
• Dunning: a failed payment isn't churn yet — retry with backoff (e.g. days 1/3/5/7), combined with smart retry (avoid issuer decline peaks), email reminders, and finally downgrade to unpaid. This is the key revenue-recovery lever for SaaS.
• Revenue recognition (RevRec): annual prepay collects cash once but recognizes revenue monthly (ASC 606 / IFRS 15) — the Ledger separates "cash collected" from "revenue recognized"; prepayment is a liability, converted to revenue month by month.
• Pricing experiments: version the Pricing Catalog, new prices apply only to new subscriptions, grandfather existing ones (keep old price); a price change must never mutate the reference of existing subscriptions.
• Reconciliation: invoice total ⇄ payment collected ⇄ ledger revenue, reconciled line by line (hooking into Day 17's reconciliation job); any break must be locatable to a line item.

Common Pitfalls + Interview Follow-ups

Frequent follow-ups: ① Cron vs per-subscription timer for cycle billing — how do you guarantee no miss, no double? ② Walk me through mid-cycle upgrade proration step by step (by second). ③ How do you design metering for 1B usage events/day, and handle late events? ④ How does annual prepay do revenue recognition, and why separate cash from revenue? ⑤ Inclusive vs exclusive tax, and why not real-time FX for multi-currency?

Further Resources

• Stripe Billing — Subscriptions Overview & Prorations (overview / prorations): authoritative implementation of the lifecycle state machine and by-second proration.
• Stripe — Designing robust and predictable APIs with idempotency (stripe.com/blog/idempotency): the engineering basis for idempotent billing and changes.
• Stripe Billing Meters / Usage-based billing (recording usage): usage aggregation sum/count/last and official high-frequency reporting advice.
• Stripe Tax — Tax behavior & multi-currency (tax behavior): inclusive/exclusive and multi-currency tax rules.
• TigerBeetle — Debit/Credit schema (docs): modeling revenue recognition as a double-entry invariant.
• Designing Data-Intensive Applications (Kleppmann): the underlying principles of batch billing, idempotency, and reconciliation.

Going Deeper (click to expand)