๐Ÿš€ Not Getting Enough Leads or Sales? FREE Website Audit & Growth Strategy for Your Business.๐Ÿš€ Not Getting Enough Leads or Sales? FREE Website Audit & Growth Strategy for Your Business.Email Us for a Website SEO, AI Growth & Digital Transformation Audit โ€” info@webespire.com
Webespire Consulting
โ˜ฐ

SaaS Subscription Billing Architecture: What Developers Need to Plan

Plans, entitlements, proration, usage metering, taxes and failed payments: the billing decisions SaaS teams should make before writing checkout code.

SaaS subscription pricing and billing, illustrated by an orange price tag beside a row of coins

SaaS subscription billing architecture is the set of decisions that connects what a customer pays for to what the product lets them do. The core pieces are a plan catalogue, an entitlement layer that the application checks, a billing provider that charges cards and issues invoices, webhooks that keep both systems in sync, and processes for proration, usage metering, tax and failed payments. Getting these boundaries right early lets you change prices and packaging without touching feature code.

Why Billing Deserves Architecture Time

Founders often treat billing as "add Stripe later". The checkout itself is quick to build. The difficulty appears later: a sales team wants an annual plan with a custom seat count, marketing wants a free trial without a card, finance needs invoices with tax breakdowns, and an enterprise customer asks for purchase-order billing. If plan names are hard-coded throughout the application, each request becomes a code change with billing risk attached.

The Building Blocks

1. Plan catalogue

Products, prices and billing intervals live in your billing provider (Stripe Billing, Chargebee, Paddle, Recurly and similar). Keep the catalogue there and reference prices by ID rather than duplicating amounts in your code.

2. Entitlements

Entitlements answer "what can this account do?": features enabled, seat limits, usage quotas, support level. Store them in your own database, derived from the subscription, and have the application check entitlements rather than plan names. if (account.can("sso")) survives a pricing change; if (plan === "pro") does not.

3. Subscription state

Mirror the essentials locally: customer ID, subscription ID, status (trialing, active, past due, cancelled), current period end and the price IDs. The billing provider remains the source of truth for money; your copy exists so the product can make fast decisions.

4. Webhooks

Billing events arrive asynchronously: payment succeeded, payment failed, subscription updated, trial ending. Your webhook handler should verify signatures, be idempotent (the same event may arrive more than once), process events in a way that tolerates out-of-order delivery, and log everything. Stripe's webhook documentation describes these requirements in detail.

5. Usage metering (if you charge for usage)

Record billable events in your own system first, aggregate them, and report totals to the provider. Keep raw usage records so you can answer disputes and recalculate if pricing changes.

A Simple Data Model

TableKey fieldsPurpose
accountsid, billing_customer_idThe paying organisation
subscriptionsaccount_id, provider_subscription_id, status, period_endLocal mirror of the subscription
subscription_itemssubscription_id, price_id, quantitySeats or add-ons
entitlementsaccount_id, key, value, sourceWhat the product allows
usage_eventsaccount_id, metric, quantity, occurred_at, idempotency_keyRaw metered usage
billing_eventsprovider_event_id, type, processed_atWebhook log for idempotency

Decisions to Make Before Coding

  • Pricing model. Flat, per seat, tiered, usage-based or a hybrid. Hybrids (base fee plus usage) are common and need both entitlements and metering.
  • Trials. With or without a payment method, and what happens on day one after expiry.
  • Upgrades and downgrades. Immediate with proration, or at the next renewal. Downgrades usually apply at renewal to avoid refunds and confusion.
  • Seat changes. Who can add seats, whether additions are billed immediately, and how removals work.
  • Annual and monthly. Switching between them mid-term needs clear rules.
  • Enterprise exceptions. Invoiced billing, custom terms and manual entitlements. Model these as a source of entitlements so they do not bypass your logic.
  • Currency. Many Canadian SaaS companies price in USD for international buyers and CAD for domestic ones. Decide early, because changing currency on existing subscriptions is awkward.

Tax

Sales tax on software varies by jurisdiction. In Canada, GST/HST and provincial sales taxes can apply to digital services depending on the buyer's location; in the US, many states tax SaaS and rules differ by state. Use your provider's tax features or a dedicated tax service, store the customer's billing address and tax IDs, and get advice from an accountant on where you have obligations. Do not hard-code rates.

Failed Payments and Dunning

Card payments fail for ordinary reasons: expired cards, bank declines, insufficient funds. Plan a dunning process:

  1. Automatic retries on a schedule set in the billing provider.
  2. Emails asking the customer to update their payment method, with a secure link.
  3. A grace period during which the account keeps working, shown with an in-app banner.
  4. A defined downgrade or suspension step, never data deletion without notice.

Security and Compliance

Let the provider's hosted checkout or elements collect card details so card data never touches your servers. This significantly reduces your PCI DSS scope. Restrict who can issue refunds or credits, log administrative billing actions, and keep webhook secrets in a secrets manager.

Testing Billing

Billing bugs cost money and trust. Use the provider's test mode and test clocks (where available) to simulate renewals, trial endings and failed payments. Write automated tests for the entitlement logic, and run a manual end-to-end check of upgrade, downgrade, cancellation and reactivation before each pricing change.

Cost and Timeline Considerations

A straightforward flat or per-seat model using a hosted checkout is usually days to a couple of weeks of engineering. Usage-based billing, multiple currencies, enterprise invoicing and custom proration rules add weeks, mostly in edge cases and testing. Provider fees are typically a percentage of revenue, so compare them with the engineering time they save.

Recommendations

  1. Keep prices in the billing provider and reference them by ID.
  2. Build an entitlement layer and check it everywhere instead of plan names.
  3. Make webhook handling idempotent and observable.
  4. Decide upgrade, downgrade, trial and dunning rules in writing before coding.
  5. Get tax advice and use automated tax calculation.

How Webespire Consulting Can Help

Our SaaS development team designs billing and entitlement models, integrates providers such as Stripe through our API development and integration work, and tests the renewal and failure paths that cause most billing incidents. If you are still choosing tools, see our guide to choosing a SaaS technology stack.

Frequently Asked Questions

Should we build our own billing system?

Rarely. Providers handle card processing, invoices, retries and much of the tax work. Build the entitlement layer yourself and let the provider handle money movement.

Where should entitlements live?

In your application database, derived from subscription data and updated by webhooks, so feature checks are fast and do not call the billing API on every request.

How do we handle a customer who wants to pay by invoice?

Most providers support invoice-based collection. Model the customer's entitlements the same way as card customers, with the source recorded as a contract.

When should we add usage-based pricing?

When usage clearly tracks the value customers receive and you can meter it reliably. Start by recording usage even before you charge for it, so you have data to set prices.

What is the most common billing bug?

Entitlements drifting out of sync with the subscription after a missed or duplicated webhook. Idempotent handlers and a periodic reconciliation job prevent it.

Conclusion

Subscription billing is a product capability, not a payment form. Separate prices, subscriptions and entitlements, handle webhooks carefully, and write down the commercial rules before the first line of checkout code. That structure lets the business experiment with pricing while engineering stays focused on the product.

Further Reading

Designing pricing and billing for a SaaS product? Email info@webespire.com or visit webespire.com.