SaaS Subscription Architecture on Stripe: What to Model Where
The boundary between Stripe's billing state and your app's entitlement state is the whole design.
Zeeshan
Founder · Published
The boundary between Stripe's billing state and your app's entitlement state is the whole design.
Zeeshan
Founder · Published
Every SaaS billing system eventually answers two questions: what is this account being charged, and what is it allowed to do. Stripe should own the first. Your application must own the second. Most billing pain traces back to blurring that line.
A subscription can be past_due while the account should still have access, because Stripe is mid-retry and the customer has not actually churned. It can be active while a specific feature stays locked, because that feature is an add-on. Map Stripe status onto an entitlement decision explicitly: do not treat them as the same field.
Upgrades and downgrades are trivial API calls and non-trivial business decisions. Stripe will happily prorate mid-cycle, credit the unused portion, and invoice the difference immediately, or defer everything to the next cycle. Both are correct; they are just different products.
Decide your proration policy before you write the upgrade endpoint. Retrofitting it means reissuing invoices for customers who already paid under the old behavior.
Metered billing inverts the flow. The amount is unknown until the period closes, which means your app is the source of truth for usage and must report it to Stripe reliably. That reporting path needs the same care as a payment path: retries, idempotency, and a reconciliation job that catches drift.
Card updates, plan changes, invoice history, and cancellation are the four highest-volume billing support categories, and Stripe's Customer Portal handles all of them as configuration rather than code. Build custom billing UI only for what the Portal genuinely cannot express: usually enterprise tiers and usage dashboards.
Stripe insights, monthly
One email a month, no spam, unsubscribe anytime.
No spam, unsubscribe anytime.
Full Stripe Billing implementation: plans, upgrades, dunning, all handled.
Learn moreA branded, self-serve portal that cuts support tickets.
Learn moreAccurate, auditable usage-based billing on Stripe.
Learn moreRobust, idempotent recurring-payment infrastructure on Stripe.
Learn moreThe five architectural decisions that determine whether your marketplace payments scale cleanly.
Let Stripe own the billing state and Django own the entitlement. Mixing the two is where it goes wrong.
Proration is where most custom billing bugs live. Here's the mental model that actually holds up.