Subscription Billing Architecture & Pricing Models

A subscription billing engine is the part of a SaaS platform where correctness is non-negotiable: every state transition either collects revenue you are owed or refunds money you are not. Integrating a payment gateway is the easy 10%. The hard 90% is the deterministic machinery around it — idempotent event processing, a finite-state model of every subscription, and an immutable ledger that survives gateway outages and still reconciles to the cent. This page is the architectural reference for that machinery. It covers how a billing engine models money and time, where it commonly breaks, and the patterns that keep it auditable as you scale from a handful of customers to six figures of active contracts.

The engine has to do several things at once. It must represent flexible monetization — flat, tiered, and metered plans combined through Hybrid Pricing Models — without letting pricing logic leak into payment execution. It must move subscriptions through Subscription Lifecycle States only along legal transitions. It must reconcile partial billing periods through Proration Logic & Calculations when customers upgrade or downgrade mid-cycle. It must ingest consumption at volume through Usage-Based Billing Implementation, and it must convert trials cleanly through disciplined Trial Period Management. Each of those is its own subsystem, but they share one spine: a price book, a state machine, and a ledger, wired together by an event bus that guarantees at-least-once delivery with exactly-once effects.

The reason this architecture is worth getting right on day one is that billing bugs are uniquely expensive. A rendering bug shows a wrong pixel; a billing bug charges a real customer the wrong amount, and the fix involves refunds, apologies, and sometimes a regulator. Worse, billing errors compound silently: a proration rounding mistake or a dropped usage event does not crash — it quietly under- or over-bills for months until someone reconciles the books. The disciplines on this page — deterministic math in integer minor units, an idempotent webhook consumer pattern, a strict subscription FSM state machine, and double-entry ledger posting — exist to make those silent failures loud, or impossible.

Architecture Overview

The billing engine is best understood as a pipeline. A signed event arrives from the payment gateway, passes a signature check and an idempotency gate, mutates subscription state inside a single transaction, and writes both a ledger entry and an outbox row atomically. A separate relay drains the outbox to the event bus, where the tax service, invoicing service, and analytics consumers subscribe. The ledger — not the gateway — is the system of record.

The table below summarizes the responsibility of each service and what it must never do.

Decoupling these lets each scale and fail independently. A tax provider outage degrades to a queued fallback rate; it does not block invoice generation across every tenant. The boundary that matters most is the one between deciding what to charge (your engine, your price book, your rules) and executing the charge (the gateway). Keep that seam clean and you can switch gateways, run two in parallel for redundancy, or move a region to a local acquirer without rewriting your monetization logic. Blur it — by letting Stripe Billing own your plan catalog, say — and every pricing experiment becomes a vendor migration. The Stripe Billing vs Paddle vs custom engine decision hinges almost entirely on where you draw this line.

Two ordering guarantees make or break this pipeline. First, events for the same subscription must be applied in causal order even though the gateway makes no such promise — a customer.subscription.updated can arrive before the customer.subscription.created it depends on, or a webhook can be redelivered hours later after a timeout. A monotonic event_sequence per aggregate, checked at apply time, lets the engine hold or drop an event that arrives out of order rather than folding stale data into current state. Second, publication must never precede commit: the outbox relay only ever sees rows the source transaction already wrote durably, which is exactly why the outbox row and the state mutation share one transaction instead of being two independent API calls that can partially fail. Nearly every other rule in this architecture is a consequence of protecting those two invariants.

A useful test for any new billing feature is to ask where it sits on the decide → execute → record spine. Deciding is pure computation over the price book and subscription state; it should be replayable with no side effects, which means it is trivially unit-testable and safe to run twice. Executing is the single step that touches the gateway and the only one permitted to fail for reasons outside your system. Recording is the ledger write that makes the outcome permanent and auditable. Features that smear across these phases — a discount rule that calls the gateway, a webhook handler that computes proration inline and captures a charge in the same breath — are the ones that later resist testing, because you cannot exercise the decision without moving real money. Keeping the three phases in separate, individually testable units is what lets a billing engine grow in scope without its blast radius growing with it.

Core Data Model

Money is stored as integer minor units (BIGINT cents), never floats. Prices are versioned and immutable: a price record is never edited, only superseded, so historical invoices always reconstruct against the price that was in effect. Subscriptions reference a price_id snapshot rather than a mutable plan row. The entity relationships below show why: the invoice and ledger rows point at the exact price version that produced them, so a price change tomorrow can never rewrite what a customer was billed yesterday.

-- Versioned, immutable price records (minor units / cents)
CREATE TABLE prices (
  price_id        UUID         PRIMARY KEY DEFAULT gen_random_uuid(),
  product_code    TEXT         NOT NULL,
  version         INT          NOT NULL,
  currency_code   CHAR(3)      NOT NULL,
  unit_amount     BIGINT       NOT NULL CHECK (unit_amount >= 0),  -- cents
  billing_model   TEXT         NOT NULL CHECK (billing_model IN ('flat','tiered','metered')),
  tier_structure  JSONB,                                          -- NULL for flat
  effective_at    TIMESTAMPTZ  NOT NULL,
  created_at      TIMESTAMPTZ  NOT NULL DEFAULT now(),
  UNIQUE (product_code, version)
);

CREATE TABLE subscriptions (
  subscription_id      UUID         PRIMARY KEY DEFAULT gen_random_uuid(),
  customer_id          UUID         NOT NULL,
  price_id             UUID         NOT NULL REFERENCES prices(price_id),
  status               TEXT         NOT NULL
                         CHECK (status IN ('trialing','active','past_due','canceled')),
  current_period_start TIMESTAMPTZ  NOT NULL,
  current_period_end   TIMESTAMPTZ  NOT NULL,
  state_version        BIGINT       NOT NULL DEFAULT 0,  -- optimistic lock
  CHECK (current_period_end > current_period_start)
);

-- Append-only double-entry ledger; posted rows are immutable
CREATE TABLE ledger_entries (
  ledger_entry_id  UUID         PRIMARY KEY DEFAULT gen_random_uuid(),
  invoice_id       UUID,
  customer_id      UUID         NOT NULL,
  account_code     TEXT         NOT NULL,         -- e.g. 1000_CASH, 4000_REVENUE
  direction        TEXT         NOT NULL CHECK (direction IN ('debit','credit')),
  amount           BIGINT       NOT NULL CHECK (amount > 0),  -- cents
  currency_code    CHAR(3)      NOT NULL,
  idempotency_key  TEXT         NOT NULL,
  posted_at        TIMESTAMPTZ  NOT NULL DEFAULT now(),
  UNIQUE (idempotency_key, account_code, direction)
);

The state_version column drives optimistic concurrency on lifecycle transitions; the idempotency_key uniqueness on ledger_entries makes every posting replay-safe. Storing tier_structure as JSONB keeps tiered and flat plans in one table while leaving threshold math to the rating engine. Three schema decisions here pay for themselves repeatedly: immutable prices mean historical reconstruction is a JOIN, not a guess; the ledger’s composite unique constraint turns “did I already post this?” into a database-enforced fact rather than an application check that races; and a state_version on the subscription lets two concurrent webhook workers fight over the same row safely, with one winning and the other retrying against fresh state. The full treatment of the ledger side lives in Building an immutable double-entry billing ledger in PostgreSQL; the pricing side is expanded in Designing tiered vs flat-rate subscription databases.

Two modeling choices deserve emphasis because they are cheap to make now and expensive to retrofit. The first is currency. A currency_code on every monetary row — price, invoice line, and ledger entry — is not optional even if you launch in a single market, because the day you add a second currency you do not want to migrate a billion historical rows to add the column and backfill it. Store the currency next to every amount and treat “amount without currency” as a type error in your code. The second is the entitlements boundary. What a customer is allowed to do (seats, feature flags, usage quotas) is derived from their subscription but should live in its own entitlements projection, rebuilt from subscription events, rather than being read directly off the subscriptions row. That separation lets the product check entitlements at request latency without touching billing tables, and it means a billing correction never accidentally revokes access mid-request.

Note also what the schema deliberately omits: there is no plan_name string denormalized onto the subscription, no monthly_price column that could drift from the price book, and no boolean is_active shadowing the status enum. Every one of those would be a second source of truth that eventually disagrees with the first. The rule is that anything derivable is derived — balances from ledger entries, entitlements from events, the amount due from the price version — so there is exactly one place a given fact can be wrong, and one place to fix it.

Physically, the two tables that grow without bound are ledger_entries and any raw usage-event store, so both want a partitioning strategy from the start. Range-partitioning the ledger by posted_at month keeps the hot partition small, makes period-close a matter of freezing old partitions, and lets you archive cold months to cheaper storage without touching the query path. Index the ledger on (customer_id, posted_at) for balance queries and carry the UNIQUE (idempotency_key, account_code, direction) constraint as the correctness backstop rather than as a query index. Resist the temptation to add columns to ledger_entries as reporting needs grow: the ledger is a narrow, append-only fact table, and every reporting dimension you need — product, region, tax code — belongs on the invoice or a separate dimension table that the ledger row references, so the fact rows stay small and immutable forever.

A last word on identity. Use opaque UUID primary keys rather than sequential integers for every externally visible entity, so a customer cannot enumerate their neighbors’ invoice IDs and so a merge or shard-rebalance never collides. Where you genuinely need a human-facing sequential number — invoice numbers are the classic case, because tax authorities require a gap-free sequence — generate that number in its own dedicated, transactional counter rather than reusing the primary key, a subtlety covered in generating compliant sequential invoice numbers.

Key Design Patterns

Four patterns recur throughout a billing engine. None is exotic on its own; the discipline is applying all four consistently so that no money movement escapes them. The matrix below places each pattern against the failure it prevents and where in the pipeline it lives.

Outbox pattern

Write the domain mutation and the event to publish in the same transaction, then relay the event asynchronously. This makes “state changed” and “event published” atomic without distributed transactions.

BEGIN;
UPDATE subscriptions
   SET status = 'active', state_version = state_version + 1
 WHERE subscription_id = $1 AND state_version = $2;  -- ✅ optimistic guard

INSERT INTO outbox (event_id, aggregate_id, event_type, payload)
VALUES (gen_random_uuid(), $1, 'subscription.activated', $3);
COMMIT;  -- ⚠️ if this fails, neither the state nor the event escapes

Use it whenever a state change must reliably produce a downstream event. A separate relay polls outbox and publishes with at-least-once delivery; idempotent consumers make the net effect exactly-once. The complete relay design, including how to avoid double-publishing under concurrent pollers, is in Using the outbox pattern for reliable billing events.

Idempotency keys

Every mutating endpoint and every consumer keys on a deterministic token. Duplicate deliveries return the cached result instead of re-charging.

def process_billing_event(event_id: str, payload: dict) -> dict:
    if (cached := idempotency_store.get(event_id)) is not None:
        return cached  # ✅ replay returns prior result, no side effects
    with db.transaction():
        result = apply_business_logic(payload)
        idempotency_store.set(event_id, result, ttl=86400)  # ≥ retry window
    return result

Use it on webhook ingress and any client-facing POST that moves money. The choice of store — Redis for speed, Postgres for durability — is a real trade-off covered in Redis vs Postgres for webhook idempotency keys.

Finite-state machine

Subscription status changes only along declared edges. Illegal jumps are rejected before any ledger effect.

LEGAL = {
    "trialing": {"active", "canceled"},
    "active":   {"past_due", "canceled"},
    "past_due": {"active", "canceled"},
    "canceled": set(),  # ✗ terminal
}

def assert_transition(current: str, target: str) -> None:
    if target not in LEGAL[current]:
        raise ValueError(f"illegal transition {current} -> {target}")

Use it to keep out-of-order gateway events from corrupting state — a late payment_failed cannot reactivate a canceled subscription.

Double-entry posting

Every financial movement posts a balanced debit and credit. Balances are derived, never stored mutably.

INSERT INTO ledger_entries (customer_id, account_code, direction, amount, currency_code, idempotency_key)
VALUES
  ($1, '1000_CASH',    'debit',  $2, 'USD', $3),
  ($1, '4000_REVENUE', 'credit', $2, 'USD', $3);

Use it for every charge, credit, refund, and tax movement so the books always reconcile to zero.

The reason to insist on all four together, rather than picking the two that feel most urgent, is that they compose into a single guarantee no one of them provides alone. Idempotency keys make a delivery safe to repeat; the outbox makes a state change safe to publish; the FSM makes an event safe to apply out of order; double-entry makes the result safe to audit. Drop any one and a gap opens: idempotency without an outbox still loses events on a crash between commit and publish; an outbox without an FSM still applies a stale event to current state; an FSM without double-entry still leaves you unable to prove the books balance after a messy day. Applied as a set, they turn “we think billing is correct” into “billing is correct by construction, and here is the ledger that proves it.” Each pattern gets a full standalone treatment in the webhook and reconciliation clusters; the point at the architecture level is that they are not four independent choices but one interlocking discipline.

Compliance & Regulatory Boundaries

PCI-DSS scope is minimized by never letting a primary account number touch your servers. The gateway tokenizes the card; you store only a token reference. This is the single most important architectural boundary in the payment path. GDPR and CCPA impose data minimization and right-to-erasure — but financial records carry a statutory retention period (commonly seven years), so erasure must pseudonymize the customer while preserving the ledger.

Payment authentication adds a third regulatory axis. In Europe, PSD2 Strong Customer Authentication requires a 3DS challenge on many transactions, and — critically for a subscription engine — the rules distinguish the first customer-initiated payment from subsequent merchant-initiated ones. Your first charge sets up an off-session mandate; renewals ride that mandate and are usually exempt, but an issuer can still soft-decline and demand re-authentication, which your dunning flow must handle by pulling the customer back on-session rather than silently failing. Designing for this means storing enough of the original authentication context (the mandate reference, the exemption claimed) to argue liability if a payment is disputed. The checkout-side mechanics of the challenge live in the SCA/3DS2 challenge flow work; the billing engine’s job is to record which authentication path each charge took.

Data residency is the boundary teams discover last and regret most. Some jurisdictions require that personal and financial data about their residents be stored in-region, which turns “one global Postgres” into “one ledger per region with a routing layer above it.” The cheap insurance is to make tenant-to-region a first-class attribute early, even if every tenant currently lives in one region, so that adding a second region is a deployment exercise rather than a schema migration. The ledger’s immutability helps here too: because postings never move, replicating a region’s ledger for disaster recovery is a straightforward append-only stream rather than a mutable-state sync with all its conflict headaches.

A last architectural note on evolution, because a billing engine is never finished. Plans change, tax rules change, and gateways change, so the engine must absorb new pricing shapes and new compliance requirements without a rewrite each time. The property that makes this possible is that the price book is data, not code: a new plan shape is a new row and a rating rule, not a schema migration and a deploy. Where a genuinely new mechanism is needed — a first usage-metered plan, a first multi-currency market — it slots in behind the same decide/execute/record spine, because that spine is agnostic to what is being decided. Teams that hard-code the current plan catalog into their charging logic pay for it later as a migration every time pricing evolves; teams that keep monetization as versioned data treat a pricing change as a content change. The single best predictor of whether a billing engine will age well is whether its pricing lives in rows you can add to or in branches you have to edit.

It is worth closing on the human side of this architecture, because the failure that most often sinks a billing engine is organizational, not technical. Billing sits between engineering, finance, and support, and each speaks a different language about the same events: engineering says “webhook,” finance says “revenue,” support says “the customer was charged twice.” The immutable ledger is the shared vocabulary that lets the three talk without translation loss — every dispute resolves to “show me the ledger entries for this customer,” and the entries are the same facts whether an engineer, an accountant, or a support agent is reading them. Investing early in a ledger that non-engineers can query (through a read model with human-legible account names and timestamps) pays back disproportionately, because it turns cross-functional billing arguments into lookups. A team that keeps its financial truth locked inside application code that only engineers can interpret will spend years relitigating the same “is this number right?” question; a team whose ledger is the single legible source of truth answers it once, definitively, every time.

Finally, resist the urge to optimize prematurely. Everything on this page — sharded runs, partitioned ledgers, circuit breakers, regional sub-ledgers — is load-bearing at scale and pure overhead before it. A product with a few thousand subscriptions needs the correctness disciplines (integer money, idempotency, the FSM, double-entry) from day one, because those are cheap to adopt early and ruinous to retrofit, but it does not need hash-sharding or multi-region ledgers until the numbers demand them. The art is knowing which decisions are one-way doors that must be right immediately — the money representation, the immutability of the ledger, the decide/execute/record separation — and which are two-way doors you can defer until real load tells you their shape. Get the one-way doors right on day one and you buy yourself the freedom to make every other decision late, with data instead of speculation. The corollary is a useful review question for any proposed billing change: is this a one-way door or a two-way door? If it changes how money is represented, whether history is immutable, or where the decide/execute/record boundary falls, it deserves the scrutiny of a decision you cannot cheaply reverse. If it is a scaling or performance choice, ship the simple version and let production tell you when to revisit it.

Tax is resolved per line item at invoice generation, because a flat subscription fee and a usage overage can fall under different tax codes and jurisdictions. The exact rate applied must be snapshotted onto the invoice; never recompute historical tax from current rules. Revenue recognition follows ASC 606 / IFRS 15: cash collected up front sits in a deferred-revenue liability account and is recognized over the service period, not at the moment of payment. The ledger schema above gives you the audit trail regulators expect — immutable, timestamped, and traceable to a source event. For the accounting-side detail see Revenue Recognition & ASC 606 and, for the tax-side detail, VAT & GST Tax Calculation.

Scalability & Failure Modes

At a few thousand subscriptions, a naive nightly batch that iterates every subscription in one transaction works. At 10k it starts to time out; at 100k it will not finish inside the billing window. The fix is to shard invoice generation by customer_id hash and process shards in parallel, each in its own short transaction. Renewal due-dates should be jittered across the day rather than all firing at midnight UTC, or you create a thundering herd against the gateway and your own database.

Concrete numbers help size this. A single Postgres primary comfortably sustains a few thousand short billing transactions per second, but each renewal is not one transaction — it is a rating computation, a gateway round-trip of 200–800 ms, an invoice write, and a ledger posting. The gateway latency, not your database, is the binding constraint, which is why the worker pool must be sized against gateway concurrency limits rather than CPU. Route all reporting and reconciliation reads to a replica so a heavy finance query never contends with the write path that is trying to close the billing window. And keep the transaction that holds the subscription row lock as short as physically possible: do the gateway call outside the transaction, then reopen a short transaction to record the result, so a slow acquirer never pins a row lock for a full second while other events for that customer queue behind it.

The dangerous cascade is the tax or payment provider going slow rather than down. Synchronous calls pile up, connection pools exhaust, and an unrelated tenant’s request blocks. Wrap every external call in a circuit breaker with a timeout well below your pool’s patience, and fall back to a queued retry with a default jurisdictional rate so invoices still generate. Retries use exponential backoff with jitter; the idempotency key guarantees a retried charge is never a double charge. Out-of-order webhooks are absorbed by the FSM and a monotonic event_sequence cursor, so a stale event is dropped rather than applied. The retry and backoff mechanics are detailed in Webhook Retry & Timeout Strategies, and the metering side of scale in Designing a high-throughput metering event pipeline.

Operational Runbook

Monitor the outbox lag (rows where published_at IS NULL older than N seconds) — sustained growth means the relay is stuck and downstream state is drifting. Alert when the dead-letter queue for webhook processing crosses a small threshold; a spike usually means a deploy broke a consumer. Track the gateway settlement-to-ledger reconciliation gap daily: a non-zero unmatched balance is a correctness bug, not a rounding artifact, and should page someone. The signals worth wiring to a pager, and the thresholds that make them actionable rather than noisy, are summarized below.

Run a nightly reconciliation job that sums ledger debits and credits per currency and asserts they net to zero, and that compares gateway payout reports against 1000_CASH postings. A daily “fractional cent” sweep reconciles accumulated rounding remainders so they never silently leak. Keep period-close locking strict: once a financial period is closed, no row may post into it; corrections post as new dated reversing entries. The full reconciliation and settlement workflow, including how to diff a Stripe payout report against your ledger, is covered in Reconciliation & Double-Entry Ledger.

Two operational habits separate teams that sleep at night from teams that firefight. The first is a rehearsed replay procedure: because every state change originates from an idempotent event, you should be able to re-drive a consumer from a checkpoint after a bad deploy and trust the idempotency keys to make the replay a no-op for anything already applied. Practice this in staging before you need it in production, because the failure mode you want to avoid is discovering during an incident that a “replay-safe” consumer was quietly not. The second is a documented money-movement escalation path. When the daily reconciliation gap is non-zero, the on-call engineer needs to know, in order: which payout it traces to, which subscriptions posted into that window, and who in finance signs off on a correcting entry. Writing that runbook down turns a scramble into a checklist, and the checklist is also the artifact an auditor will ask to see.

Frequently Asked Questions

How do you guarantee exactly-once effects across distributed billing services? Combine an idempotency-key store with the outbox pattern. The idempotency store makes any single consumer replay-safe — duplicate deliveries return the cached result. The outbox makes the state change and the event publication atomic in one transaction, so you never publish an event for a change that rolled back. Together they give at-least-once delivery with exactly-once effect.

Where should pricing logic live — in the gateway or your own engine? Keep pricing rules in your own versioned price book and treat the gateway purely as a payment executor. Embedding tiers, entitlements, and proration in the gateway couples your monetization to one vendor and makes audits harder. Resolve the amount yourself, then hand the gateway a final figure to capture.

Why store money as integer cents instead of a decimal type? Integer minor units eliminate an entire class of floating-point drift and serialization bugs across language boundaries. You do high-precision intermediate math (proration, tiered rating) in a decimal type, then round once to integer cents at the line-item boundary before persisting.

How do you handle a subscription that changes plan twice in a few seconds? Serialize the changes with optimistic concurrency (state_version) or a row lock, and key each resulting ledger posting on subscription_id + change_timestamp + target_price_id. The FSM rejects illegal intermediate transitions, and the idempotency keys prevent the rapid toggling from producing duplicate proration lines.

What is the minimum viable compliance posture before charging real cards? Tokenize through a PCI-compliant gateway so PANs never reach your servers, snapshot tax rates per invoice line, post all money movements to an immutable double-entry ledger, and defer recognized revenue per ASC 606. Those four boundaries cover the bulk of what an early audit will ask for.

Should we build our own billing engine or adopt Stripe Billing or Paddle? It depends on how much pricing flexibility and vendor independence you need. Off-the-shelf billing is fastest to launch and offloads compliance, but constrains your catalog and locks in your monetization. A custom engine is more work but keeps the decide-versus-execute boundary clean. Walk the trade-off in detail on Stripe Billing vs Paddle vs custom engine.

How do you migrate the billing engine without a maintenance window? Treat the ledger as the invariant and migrate around it. Run the new engine in shadow first: feed it the same event stream, let it produce ledger postings into a separate schema, and diff those postings against the live engine’s for a full billing cycle. Only cut over once the shadow ledger reconciles to the cent against production for several cycles. Because subscriptions are driven by idempotent events rather than mutable state, you can replay history into the new engine and expect identical output — that reproducibility is what makes a zero-downtime cutover possible at all.

How should test and production billing data be isolated? Never let test-mode gateway events post into the real ledger, and never let a staging replay reach a live acquirer. The clean separation is a livemode boundary carried on every event and enforced at the idempotency gate, so a test webhook and a production webhook can share code but never share an idempotency namespace or a ledger. Mixing them is a classic source of phantom revenue that only surfaces at reconciliation, weeks later.

Related

• Hybrid Pricing Models for SaaS
• Proration Logic & Calculations
• Subscription Lifecycle States
• Usage-Based Billing Implementation
• Trial Period Management
• Entitlements & Feature Gating
• Enterprise Contracts & Quote-to-Cash
• Webhook Processing & Backend State Management
• Reconciliation & Double-Entry Ledger