System Design

Subscription Billing

Design a recurring subscription billing system like Stripe Billing or Chargebee.

Functional requirements

• Merchants define plans with a price and billing interval (e.g., Pro at $20 per month), and customers subscribe to a plan with a saved payment method.
• On each renewal date the system charges the saved payment method for the plan price through an external card processor and records an invoice with a status (paid, failed, or past due).
• When a charge fails, the system retries on a schedule (e.g., after 1, 3, and 7 days) and emails the customer to update their card; after the final failed retry the subscription is canceled.
• Customers can upgrade, downgrade, or cancel; a plan change takes effect at the next billing period, and a cancellation stops future charges.
• Merchants and customers can view invoice history and a subscription's current status and next billing date.

Non-functional requirements

• Exactly one charge per subscription per period: a customer is never charged twice for the same period, even when workers crash, restart, or run concurrently, and never skipped when the scheduler runs late.
• Every renewal is attempted within 1 hour of its due time in normal operation; a scheduler outage of several hours is caught up automatically without double charging.
• p99 under 200ms for subscription status and invoice reads; charge attempts run in the background and may take several seconds each.
• Correctness over availability: if the database or the card processor is unreachable, charges are deferred and retried later; a late charge is acceptable, a duplicate is not.
• Invoices and charge records are durable for 7 years; no acknowledged invoice or plan change may be lost, and card numbers are never stored, only the processor's token.

Scaling & constraints

• 10,000 merchants with 30M active subscriptions; ~1M renewals due per day on average, and the 1st of the month carries ~5x that (~5M).
• Renewals are processed by a fleet of ~50 worker instances that are deployed, restarted, and autoscaled several times a day.
• Read:write ratio is roughly 30:1 (status and invoice reads from dashboards and customer portals vs. charges and plan changes).
• Each subscription record is ~1 KB and each invoice ~2 KB; invoices are retained for 7 years and subscription volume grows ~40% per year.
• The external card processor has p50 latency of 500ms, p99 of 4s, ~0.5% timeouts (some after the charge succeeded), and an ~8% first-attempt decline rate on renewals.
• About 15% of subscriptions change plan or cancel in a given month, and ~80% of those changes land in the last 3 days of the period.

Out of scope

• Proration, usage-based metering, and tax calculation.
• The card processor itself (assume a charge API that accepts an idempotency key).
• Merchant onboarding, checkout pages, and payment method collection.
• Revenue recognition, accounting exports, and multi-currency.