Fast. Simple. No meetings. No delays.
Home / Blog / SaaS / Implementing SaaS Subscription Billing: Plans, Proration and Dunning

Implementing SaaS Subscription Billing: Plans, Proration and Dunning

The implementation details of subscriptions: plan models, proration on upgrade, failed-payment retries, webhooks and invoice records.

Cover graphic for the article: Implementing SaaS Subscription Billing: Plans, Proration and Dunning

SaaS subscription billing implementation comes down to a few decisions: model plans separately from what customers are entitled to, let the payment provider own the billing clock, drive your own state from verified webhooks, and keep an audit trail of every invoice and change. Get those right and proration, retries and refunds become manageable.

This is the implementation view. For the earlier planning questions, such as which provider to pick and when to bill, read setting up subscription billing for an early-stage SaaS. The provider-integration basics are in adding Stripe or PayPal to a web application.

Model plans and entitlements first

Keep three ideas apart in your data model, because mixing them is the most common source of billing pain later:

  • Plan or price: what you charge, in which currency, at which interval. This usually lives at the provider and is referenced by an ID.
  • Subscription: the relationship between one customer (or account) and a plan, with a status and a current period.
  • Entitlement: what the customer may actually do: seat limits, feature flags, usage allowances.

Your application should check entitlements, never plan names. A check like can('export_pdf') survives a repricing or a new plan; a check like plan === 'pro' breaks every time marketing adds a tier. Map each plan to a set of entitlements in your own configuration, and compute the customer's current entitlements from their subscription state.

Decide early how you handle seats, usage-based charges and add-ons, since each changes what a subscription item looks like. If your product is multi-tenant, decide which entity holds the subscription: the user, the organisation or the workspace. The multi-tenancy options for Laravel SaaS article covers how that choice interacts with tenant structure.

Trials and coupons

A trial is a subscription state with an end date, not a separate system. Decide the rules in writing before building:

  • Is a payment method required to start? Requiring one usually means fewer but more committed trials, and you must handle the first charge failing.
  • What happens at the end: convert to paid automatically, downgrade to a free tier, or lock the account? Which data stays readable?
  • Can the same customer trial twice? Decide how you detect repeats, and be careful that the method does not become intrusive.
  • Do trials extend if a customer is mid-onboarding? If support can extend them, record who did it and why.

Coupons need the same care. Define whether they apply once or for a number of cycles, whether they stack, and what they do on plan changes. Store the coupon applied on each invoice so finance can explain a discount later.

Proration on change

Proration adjusts what a customer pays when they change plan mid-period. The principle is simple: credit the unused part of the old plan and charge the remaining part of the new one. Take a hypothetical monthly plan costing 30 that moves to a plan costing 60 exactly half-way through a 30-day period. The customer is credited 15 for the unused half of the old plan and charged 30 for the remaining half of the new plan, so the net adjustment is 15.

The difficulty is in the choices around it:

  • Upgrades: charge the difference immediately, or add it to the next invoice?
  • Downgrades: apply now with a credit, or at the end of the period? Many products defer downgrades to avoid refund handling.
  • Interval changes: monthly to annual changes the billing date, and may need a fresh period.
  • Rounding and time zones: proration may be computed by day or by second, depending on the provider.

Your provider can usually calculate proration for you, and you should check its documentation for the exact behaviour rather than assuming. Show the customer a preview of the charge before they confirm, using the provider's preview or upcoming-invoice feature where one exists, so the number on the screen matches the number on the invoice.

Failed payments and dunning

Dunning is the process of recovering a payment that failed. Cards expire, limits are hit and banks decline renewals, so failed payments are normal and need a designed response rather than a panic.

  1. Retry on a schedule. Providers usually offer automatic retries with configurable timing. Spread attempts over several days rather than hammering.
  2. Notify the customer at the first failure with a direct link to update their payment method, and again before access changes.
  3. Define a grace period during which the account works normally but shows a banner.
  4. Restrict gently. After grace, move to read-only or a limited state before full suspension. Keep the customer's data intact.
  5. Cancel or close only after a stated final deadline, and make reactivation easy.

Your entitlement logic needs a state for "past due" distinct from "active" and "canceled". Some payments require extra customer authentication; make sure your flow can send the customer back to complete it rather than treating it as a plain decline.

Webhook-driven state in a SaaS subscription billing implementation

The payment provider knows what happened; your server finds out through webhooks. Treat them as the source of truth for subscription state rather than relying on the browser returning to your success page, which users close, lose or never reach.

  • Verify signatures with the provider's method on every request, using the raw request body.
  • Respond quickly with a success status, then do the work in a queue. Slow handlers cause retries and duplicates.
  • Be idempotent. Providers can deliver the same event more than once. Store processed event IDs and skip repeats.
  • Do not assume order. An update event can arrive before the creation event. Prefer fetching the current object from the provider API when state matters, or compare timestamps or version fields.
  • Keep the raw event in a table for debugging and replay.

Add a periodic reconciliation job that compares your subscription table with the provider's records and flags differences. Webhooks do get missed, so this safety net is worth having.

Invoices and audit trail

What to store locally vs at the provider

Keep the provider's IDs (customer, subscription, invoice, payment) on your records, along with the status and period dates you need to render the app quickly. Let the provider remain the system of record for card details, which you should not hold yourself, and for the payment attempt history. Store locally anything you need when the provider is unreachable or when you change provider: customer-to-account mapping, current entitlements, invoice number, totals, currency, tax lines and a link or copy of the invoice document.

Audit trail

Log every state change with who or what caused it: webhook event, customer action, admin override. When a customer asks why they were charged, you want to answer from a table rather than from memory. Invoice rules, numbering and tax handling vary by country, so confirm requirements with the relevant authority or a qualified adviser.

Testing the lifecycle

Billing bugs surface as upset customers and wrong invoices, so test the whole life of a subscription, not only the happy path. Use the provider's test mode and its clock or simulation tools where available.

  • Sign up, trial start, trial end with and without a payment method.
  • Upgrade, downgrade and interval change at different points in the period.
  • Failed payment, retry success, retry exhaustion, and customer updating the card.
  • Cancellation at period end and immediate cancellation, then reactivation.
  • Duplicate, delayed and out-of-order webhooks.
  • Coupon applied, expired and combined with a plan change.

Automate as many of these as you can and run them before each release that touches billing.

Shortlisting a software development partner Denmark offers: next step

Start with plans mapped to entitlements, webhook-driven state with idempotent handlers, a clear dunning policy and a reconciliation job. Add complexity such as usage billing only when the product needs it. If you want a review of a billing design, see our software development overview for startups or get in touch.

Frequently asked questions

How is proration calculated?

Typically the unused part of the old plan is credited and the remaining part of the new plan is charged. If a plan costing 30 changes to one costing 60 halfway through a 30-day month, the credit is 15 and the new charge is 30. Providers differ in rounding and timing, so check their documentation.

How should dunning work?

Retry failed payments on a spaced schedule, email the customer with a direct link to update their card, and keep the account working through a defined grace period. Then restrict access gently, for example to read-only, before suspending. Keep their data intact and make reactivation easy, with a stated final deadline.

What should be stored locally vs at the provider?

Leave card details and payment attempts with the provider. Store provider IDs, subscription status and period dates, current entitlements, invoice numbers, totals, currency and tax lines locally, plus the raw webhook events. That lets your app run quickly and survive an outage or a provider change.

Related articles

🚀 Start Now