Design B2B SaaS Subscription Billing & Dunning Lifecycle
A subscription management system that manages recurring revenue, free-to-paid trial transitions, and automated revenue recovery (dunning). It recaptures up to 75% of failed credit card renewals through machine-learning retries and self-service billing portals.
Live Architecture Studio
Edit components, modify labels, add databases, or redraw connections directly on this canvas:
1. Problem & Challenge
Up to 40% of SaaS customer churn is involuntary—caused by expired cards, credit limit spikes, or bank security blocks. Hard declines versus soft declines require distinct recovery paths without interrupting legitimate user workflows.
2. Core Building Blocks & Responsibilities
👉 Swipe table horizontally to view roles and responsibilities| Component | Role | Plain-English Explanation |
|---|---|---|
| Free Trial Provisioner | Onboarding & Customer Creator | Provisions 14-day Pro tier without upfront credit cards and creates Stripe Customer records. |
| Trial Expiry Warning Hook | Notification Scheduler | Fires 3 days before trial ends to prompt card entry and explain renewal options. |
| Stripe Invoicing & Billing Engine | Recurring Invoicing Engine | Finalizes recurring renewal invoices and attempts charging default customer payment methods. |
| Dunning & Smart Retry Machine | ML Recovery Orchestrator | Listens for invoice.payment_failed and dynamically schedules ML-optimized card retries. |
| Customer Billing Portal | Self-Service Payment Gateway | Provides hosted portal for updating expired cards, reviewing tax IDs, and downloading VAT receipts. |
| Entitlement & Access Controller | Feature Flag Governor | Caches Pro feature access in Redis, managing past-due grace periods before downgrading. |
3. Step-by-Step Request Flow
Free Trial Provisioning
Customer registers; system initializes Stripe Customer and assigns 14-day Pro tier entitlement in Redis.
Trial Expiry Notification
At day 11, automated webhook prompts customer to input payment card details before trial ends.
Invoice Finalization & Charge
Trial concludes; billing engine drafts invoice and executes charge against saved card.
Payment Decline & Smart Retries
Card declines; status enters past_due, triggering Smart Retries ML engine across a 14-day window.
Customer Self-Service Update
Customer clicks dunning link, updates expiration date in billing portal, and retries payment immediately.
Payment Succeeded & Access Restored
Webhook confirms invoice payment; entitlement cache resets status to active, securing recurring revenue.
4. Architectural Trade-offs
Immediate Cutoff vs 14-Day Grace Period
Chosen: 14-Day Grace Period with Sticky Warning
Rationale: Immediate cutoffs destroy customer goodwill for accidental card expirations; grace period rescues 75% of accounts.
Fixed Interval Retries vs ML-Based Smart Retries
Chosen: Stripe ML Smart Retries
Rationale: ML determines optimal retry times based on issuing bank behavior, avoiding unnecessary card decline fees.
Interview Tip
Differentiate Hard Declines (stolen card, closed account - no retry) from Soft Declines (insufficient funds, temporary hold - retry with backoff). Emphasize caching entitlements in Redis to avoid billing API latency.
Explore Related System Blueprints
TinyURL Shortener
A URL shortener converts a long link (like a 100-character article URL) into a compact 7-character key (like tinyurl.com/xyz123) and redirects visitors in under 15 milliseconds.
API Rate Limiter
A rate limiter acts as a digital bouncer at the door of your API, ensuring each client stays within their allowed request limits (e.g. 100 requests per minute) and blocking abusive traffic.
Video Streaming CDN
Streaming high-definition video to millions of smart TVs and mobile phones requires breaking large 10GB video files into tiny 5-second chunks, encoding each into 20 different resolutions, and caching them right inside local ISP networks.
Uber Dispatch Engine
A real-time geospatial dispatch system matches riders with the most optimal nearby drivers using 64-bit H3 hexagonal indexing and 2-second batch optimization, minimizing city-wide pickup ETA and driver idle time.
Stripe Payments Ledger
A resilient financial payments architecture guarantees strict consistency (CP system) using cryptographic idempotency reservation, double-entry balanced postings, and sharded balance locks.
Figma Multiplayer Engine
A real-time multiplayer document engine uses stateful sticky session routing and server-authoritative operational ordering to sync 2D scene graphs across worldwide collaborators without locking.