Financial
Multi-tenant SaaS Billing System
Subscription, usage, and proration billing across many tenants without lost or duplicate charges.
Scale to anchor on
Hundreds of thousands of tenants, billions of metered events/day, monthly billing cycles, multi-currency.
Requirements
Functional
- Subscription plans with seats, tiers, and metered usage.
- Mid-cycle changes with correct proration.
- Invoice generation and payment collection.
- Tax and currency handling.
Non-functional
- No double-charging; no missed charging.
- Audit trail for every charge.
- Resilience to payment provider outages.
High-level architecture
A metered-usage pipeline aggregates events into per-tenant counters. A subscription engine knows each tenant's plan and computes proration. The billing engine produces invoices that flow to a payment orchestrator with idempotency. A ledger records every state change.
Components
Usage ingestion
Aggregates metered events per tenant per period.
Subscription engine
Plan and seat state; computes mid-cycle changes.
Invoice generator
Combines usage, subscription, taxes, currency into an invoice.
Payment orchestrator
Charges via processor with idempotency and retries.
Ledger
Authoritative double-entry record of all financial state.
Key decisions
Aggregate usage on a stable cadence.
Real-time aggregation is expensive and unnecessary; invoices are monthly.
Proration rules encoded as functions of plan + change event.
Mid-cycle changes are the source of most billing bugs; centralizing the logic prevents inconsistency.
Idempotent payment charges.
Retries are routine; non-idempotent charges create disputes.
Ledger is the source of truth for money.
Invoices and payments are derived views; the ledger is the audit foundation.
Pitfalls
- Real-time charging on every metered event — DB load is unjustified.
- Proration logic spread across services.
- No idempotency on payment retries.
- Floats for currency.
Follow-up questions
- How do you handle a plan change mid-cycle?
- What's the retry strategy for a failed payment?
- How does tax handling work across regions?
- What's the daily reconciliation process?