Prompt
I need a billing architecture recommendation for a product that has subscription plans, customer self-service, and failed-payment handling
Latest observation
Here’s a practical billing architecture recommendation for a product with:
- subscription plans
- customer self-service
- failed-payment handling
I’ll assume you want something robust enough for SaaS, but not overly enterprise-heavy.
Recommended architecture
Use a billing domain/service with these core components:
-
Subscription service
- Owns plans, subscriptions, upgrades/downgrades, renewals
- Keeps subscription state separate from payment state
-
Payments service or payment adapter layer
- Talks to the payment processor (e.g. Stripe, Adyen, Braintree, etc.)
- Handles payment intents, retries, webhooks, refunds, and payment method updates
-
Customer portal / self-service UI
- Lets customers:
- view current plan
- update card/payment method
- download invoices
- cancel/reactivate
- change plan
- Prefer using hosted portal components if available, or build your own with API access
- Lets customers:
-
Billing orchestration / event processing
- Consumes payment and subscription events
- Applies business rules:
- dunning
- grace periods
- entitlement changes
- suspension/reactivation
- Important: treat webhooks as asynchronous signals, not the source of truth
-
Entitlements service
- Converts subscription/billing state into product access
- Example states:
- active
- trialing
- past_due
- grace_period
- suspended
- canceled
- This avoids coupling app access directly to payment events
Core design principles
1. Separate subscription state from payment state
A subscription can be active even if a payment is temporarily failed, depending on your grace policy.
Example:
subscription.status = activepayment.status = failedaccount.status = grace_period
This separation makes failed-payment handling much cleaner.
2. Make webhooks idempotent
Payment providers often send duplicate or out-of-order events.
Your system should:
- store provider event IDs
- ignore duplicates
- process events transactionally
- make updates safe to retry
3. Use a ledger for money movement
Even if you only charge subscriptions, keep a billing ledger:
- invoices
- charges
- credits
- refunds
- adjustments
This helps with auditability and support.
4. Put retries and dunning into workflow logic
Do not hardcode failed-payment retries inside the UI or payment provider alone.
Instead:
- first failure → notify customer
- retry after X days
- second retry → notify again
- after grace period → restrict access or suspend
- once paid → restore access automatically
5. Use a source of truth for entitlements
Your app should check entitlements, not raw payment status. This prevents fragile logic spread across services.
Suggested data model
At minimum:
Customer
- id
- billing profile info
- tax settings
- default payment method reference
Subscription
- id
- customer_id
- plan_id
- status
- billing_cycle
- current_period_start
- current_period_end
- cancel_at_period_end
- trial_end
- grace_period_end
Invoice
- id
- customer_id
- subscription_id
- amount_due
- amount_paid
- currency
- status
- due_date
- provider_invoice_id
PaymentAttempt
- id
- invoice_id
- provider_payment_id
- status
- failure_reason
- retry_count
- attempted_at
PaymentMethod
- id
- customer_id
- provider_token/reference
- type
- last4
- expiry_month/year
- is_default
Entitlement
- id
- customer_id
- scope/resource
- status
- effective_from/to
Failed-payment handling flow
A solid default flow:
On renewal date
- Generate invoice
- Attempt charge automatically
- If success:
- mark invoice paid
- renew subscription
- keep active entitlements
If charge fails
- Mark invoice unpaid / payment failed
- Enter grace period
- Notify customer immediately
- Schedule retry attempts
- If customer updates payment method, retry immediately
- If payment succeeds later:
- mark invoice paid
- restore active access
- If grace period expires:
- suspend entitlements or downgrade to limited mode
- continue to allow self-service payment recovery
Optional policy variants
- Hard lock: disable product access immediately
- Soft grace: allow access for 3–14 days after failure
- Restricted mode: read-only or limited functionality during delinquency
For most SaaS, soft grace is best.
Customer self-service features to support
You should expose these either in a portal or through your app:
- view subscription status
- change plan
- update billing info
- retry payment
- download invoices/receipts
- cancel subscription
- reactivate subscription
- change billing email
- manage tax IDs / company details
- see failed-payment notices and next retry date
If possible, use a hosted payment/customer portal for PCI and maintenance reduction.
Event-driven workflow
I recommend an event-driven approach.
Example events
subscription.createdsubscription.renewal_dueinvoice.generatedpayment.succeededpayment.failedpayment.method.updatedsubscription.grace_startedsubscription.suspendedsubscription.reactivatedsubscription.canceled
Why this helps
- decouples billing from app logic
- supports retries and asynchronous payment processing
- improves auditability
- easier to add notifications, analytics, and support tooling
Operational recommendations
Notifications
Send emails or in-app notifications for:
- upcoming renewal
- payment failure
- grace period warning
- suspension
- successful recovery
- cancellation confirmation
Monitoring
Track:
- failed payment rate
- recovery rate
- time-to-recovery
- involuntary churn
- webhook failure rate
- retry success by retry number
Security and compliance
- avoid storing raw card data unless absolutely necessary
- use tokenized payment methods from a processor
- log carefully; never store full PAN/CVV
- ensure webhook signatures are verified
- keep billing and app auth separate
Build vs buy
Best option for most teams
Use a payment processor with subscription support and build:
- your subscription state machine
- entitlements
- customer-facing business logic
- notifications and dunning rules
When to buy more
If you need:
- complex invoicing
- tax/VAT automation
- multi-entity billing
- revenue recognition
- quotes and enterprise contracts
Then consider a more complete billing platform or add specialized tax/revenue tools.
A simple reference architecture
Frontend
- app UI
- billing portal UI
Backend
- auth service
- subscription service
- invoice service
- payment adapter
- entitlement service
- notification service
- webhook handler
- job queue / scheduler
External
- payment provider
- email service
- tax service
- analytics/logging
My recommendation in one sentence
Build a subscription-first, event-driven billing architecture with a separate entitlement layer, hosted/self-service customer portal, and a dunning workflow that handles failed payments gracefully through retries, grace periods, and automatic recovery.
If you want, I can also provide:
- a concrete microservices diagram,
- a database schema, or
- a failed-payment state machine for this architecture.