Billing state models

Billing Domain & State Machines

The single most destructive mistake in billing architecture is collapsing Payment, Subscription, Entitlement (Access) and Invoice (Legal Tax Document) into a single database table or boolean flag (user.is_paid = true). These four concepts have different lifecycles, different failure modes and often different authoritative systems.

1. The Four Distinct Domain Boundaries

Model and persist these four domains separately, linked by explicit correlation IDs:

1. Payment / Charge (PaymentIntent, PaymentAttempt):
   • Represents a specific money movement attempt (created -> requires_action -> processing -> succeeded | failed | canceled | refunded | disputed).
   • Authoritative source: Payment Service Provider (PSP) or Merchant of Record (MoR).
2. Subscription / Commercial Agreement (Subscription):
   • Represents the recurring commercial contract (trialing -> active -> past_due -> paused -> canceled -> expired), billing cadence, plan/price version, current period bounds (current_period_start, current_period_end) and cancellation schedule (cancel_at_period_end).
3. Product Entitlement / Access (Entitlement, QuotaGrant):
   • Represents what features, seats or usage limits the customer can exercise right now.
   • Decoupled from raw payment state: an account can have active entitlements without a payment (trials, comped accounts, enterprise wire agreements, grace periods during past_due, or remaining prepaid period after cancel_at_period_end).
4. Legal Invoice / Receipt (Invoice, CreditNote):
   • Represents the immutable accounting and tax document (draft -> issued -> paid | voided | credited).
   • Retrying a failed invoice via an invoicing API (Billingo, Számlázz.hu) must never re-charge the customer's card, and an invoice API failure must not revoke paid product access.

2. Monetary Representation & Arithmetic Invariants

• Never use IEEE 754 floating-point (number/float/double) for money: 0.1 + 0.2 !== 0.3.
• Minor integer units or fixed-point decimal:
  • Store amounts as integer minor units (amount_minor: bigint | int, e.g., cents/fillér) paired with an explicit ISO 4217 currency code (currency: 'USD' | 'EUR' | 'HUF' | 'JPY').
  • Watch zero-decimal and special-exponent currencies: JPY, KRW have 0 decimal places; HUF has minor units in some PSP APIs (Stripe expects HUF multiplied by 100 as two-decimal minor units, whereas local Hungarian gateways often take whole forints or decimals). Verify the exact exponent rule per provider!
  • For unit prices requiring sub-cent precision (e.g., $0.0004 per API token), use exact fixed-point DECIMAL(19, 6) / BigInt scaled arithmetic and define explicit rounding rules (HALF_EVEN / banker's rounding or HALF_UP) at invoice line-item aggregation time.

3. Monotonic State Transitions & Out-of-Order Events

External webhooks arrive out of order (e.g., customer.subscription.updated arriving before customer.subscription.created, or a stale payment_intent.processing arriving after payment_intent.succeeded):

• Define an explicit state transition graph; reject or ignore transitions from a terminal or newer state back to an older state.
• Track provider resource timestamps/versions or fetch the canonical current resource from the provider API when event ordering is ambiguous.
• Immutable financial history: never DELETE or overwrite historical ledger rows, charges or issued invoices; record refunds, reversals, credit notes and balance adjustments as append-only entries.