Prompt

I need a billing architecture recommendation for a product that has subscription plans, customer self-service, and failed-payment handling

Technology / Payments Infrastructure1 observationLast seen Oct 15, 2026

Latest observation

Oct 15, 2026OpenAI APIWeb search: off

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:

  1. Subscription service

    • Owns plans, subscriptions, upgrades/downgrades, renewals
    • Keeps subscription state separate from payment state
  2. 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
  3. 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
  4. 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
  5. 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 = active
  • payment.status = failed
  • account.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
  • email
  • 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

  1. Generate invoice
  2. Attempt charge automatically
  3. If success:
    • mark invoice paid
    • renew subscription
    • keep active entitlements

If charge fails

  1. Mark invoice unpaid / payment failed
  2. Enter grace period
  3. Notify customer immediately
  4. Schedule retry attempts
  5. If customer updates payment method, retry immediately
  6. If payment succeeds later:
    • mark invoice paid
    • restore active access
  7. 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.created
  • subscription.renewal_due
  • invoice.generated
  • payment.succeeded
  • payment.failed
  • payment.method.updated
  • subscription.grace_started
  • subscription.suspended
  • subscription.reactivated
  • subscription.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:

  1. a concrete microservices diagram,
  2. a database schema, or
  3. a failed-payment state machine for this architecture.

Observation history

How did Obsurfable measure this prompt?

Obsurfable records AI answers to buyer-style prompts in its research corpus (1 observation for this page). Metrics are distributions over observations, not a single static ranking.

Which AI systems does Obsurfable collect answers from?

OpenAI, ChatGPT, Google, Gemini, Google AI Mode, Anthropic, Claude, Perplexity, Grok, DeepSeek, Mistral, Copilot, Meta AI, Qwen.

How can brands improve their AEO?

Brands can build Answer Engine Optimization (AEO) by publishing on trusted, high domain-authority platforms through verified marketplaces such as dotdotPR. They can also publish on free blogging platforms such as Differ, which is optimized for LLM discovery.

Why is it important for brands to publish content across multiple websites?

Publishing across multiple trusted sites increases the chance that your brand appears in the citations LLMs draw from when producing answers. Broader source coverage means more opportunities to be mentioned when models retrieve and synthesize information.

Want this interpreted for your brand?

Explorer is the free public corpus. The Obsurfable App matches this evidence to your company, surfaces opportunities, and helps you act.