Subscription billing is a state machine with money attached. Model plans, entitlements, trials, proration, dunning and tax before you write the checkout button.
Key takeaways
- Separate the billing provider (invoices, payments, tax) from your entitlement service.
- Store customer, subscription and price IDs; derive access from the subscription state.
- Handle proration, upgrades, downgrades, cancellation and reactivation explicitly.
- Model the state and the exceptions before building the happy path.
What the system must model
- Use webhooks for payment success, failure and subscription changes; make them idempotent.
- Reconcile active subscriptions with access daily.
How to build it
- Define plans and entitlements. What the user can do, not just the price.
- Model the state. Trialing, active, past_due, canceled, paused.
- Create checkout. Provider-hosted or custom; resolve prices on the server.
- Sync webhooks. Update entitlements and invoices idempotently.
- Handle dunning. Retries, grace period and access policy.
- Reconcile. Subscription → access → revenue.
Design decisions
| Area | What to decide | Why |
|---|---|---|
| Plans | Entitlements | Do not hard-code price checks |
| Trials | Start/end and payment method | Communicate clearly |
| Proration | Upgrade/downgrade | Test the invoice |
| Dunning | Retries and grace | Define access rules |
| Tax | Provider or accountant | Confirm registrations |
| Reconciliation | Daily access check | Catch webhook drift |
Controls and reconciliation
- Keep an audit trail for money, tax and access changes.
- Make every event idempotent; retries are normal.
- Reconcile the provider, the ledger and the bank on a schedule.
- Test failure paths: declined payments, duplicate webhooks, refunds and partial payments.
- Document who owns finance, tax and technical support.
A minimum data model
| Entity | What it must hold | Why it matters |
|---|---|---|
| Customer | Identity, tax status, addresses, consent | Invoices and tax depend on it |
| Product/plan | Price, currency, tax code, effective dates | Prices change over time |
| Invoice | Lines, tax, due date, status | The legal record |
| Payment | Provider ID, amount, status, timestamps | Reconciliation |
| Credit/refund | Reason, amount, approval | Revenue and tax corrections |
| Audit event | Actor, action, before/after | Disputes and controls |
Launch checklist
- Test a full lifecycle: quote, invoice, payment, refund and credit note.
- Test a failed payment, a duplicate webhook and a manual retry.
- Reconcile a full day of transactions against the provider and the bank.
- Check tax rounding, currency formatting and negative amounts.
- Give finance a read-only view and a documented correction process.
- Monitor queue depth, failed jobs and reconciliation differences.
Failure modes to design for
| Failure | What the system should do | What to monitor |
|---|---|---|
| Duplicate webhook | Ignore by event ID; keep one ledger entry | Duplicate-event count |
| Payment timeout | Show an unknown state; reconcile, never assume failure | Pending payments |
| Price change mid-cart | Revalidate and show the new total | Price-mismatch errors |
| Partial refund | Adjust the invoice and tax proportionally | Refund reconciliation |
| Currency mismatch | Reject or convert with an explicit rate | FX differences |
| Job backlog | Alert before invoices or emails are late | Queue age |
Operational metrics
- Invoices created, paid, overdue and failed, by day.
- Reconciliation differences and the time to resolve them.
- Payment success rate by method and market.
- Tax and currency exceptions that required manual review.
- Time to close the month and the number of manual journals.
- Support tickets per hundred transactions.
Common mistakes
- Building the checkout before the billing state model.
- Trusting client-side amounts, currencies or tax rates.
- Ignoring refunds, credit notes and failed payments.
- Launching without daily reconciliation.
Frequently asked questions
Only if billing is the product. Otherwise use a provider for invoices, tax, retries and payment methods, and build the entitlement layer that matches your product.
Define proration, when the new entitlement starts and what happens to the old plan. Test the invoice and the access change together.
Retry on a schedule, notify the customer, offer a grace period and revoke access only after the policy allows. Track recovery and churn.
Derive access from the subscription state, reconcile daily and revoke on cancellation or non-payment. Do not rely on a client-side flag.
Sources and further reading
- Stripe Billing documentation (docs.stripe.com)
- Stripe webhooks documentation (docs.stripe.com)
- NIST Secure Software Development Framework (csrc.nist.gov)
Related services
Building a billing or POS flow?
Describe the plans, currencies and payment methods. I will map the state model and the reconciliation points before you build.
How to cite this guide: Nur Hossain Repon, “Build SaaS subscription billing for your business: guide”, Nhrepon Portfolio, reviewed October 2026, https://nhrepon.com/posts/build-saas-subscription-billing-for-your-business-guide.





Comments
No comments yet.