SaaS Subscription Billing with Stripe

SaaS subscription billing looks simple until you ship it: a customer upgrades mid-cycle, a card expires, a webhook arrives twice, or a buyer in another country needs tax on the invoice. Stripe handles most of the heavy lifting, but how you integrate it decides whether billing is reliable or a constant source of support tickets and revenue leakage. In this guide you will learn how to model plans in Stripe Billing, when to use Checkout and the Customer Portal, how to build a webhook-driven source of truth, and how to handle upgrades, failed payments, tax and idempotency correctly. These are the practices our custom SaaS development team uses when building billing into new and existing products.

How Stripe Billing Models a SaaS Subscription

Stripe Billing organizes subscription data around a few core objects. A Customer represents the paying account, which in a B2B SaaS should map to your tenant or organization, not to an individual user. A Product describes what you sell (for example, the Pro plan), and one or more Prices define how it is charged: monthly or annual, flat rate, per seat, tiered or usage-based. A Subscription links a Customer to one or more Prices and generates Invoices each billing period, which in turn create payments. Keep the mapping explicit in your database: store the Stripe customer ID on the tenant record and the subscription ID, status, current price and period end on a subscription table you own. Before modeling anything, settle your packaging; our guide to SaaS pricing models covers flat, per-seat, tiered and usage-based options and how each affects implementation.

Use Lookup Keys Instead of Hardcoded Price IDs

Price objects in Stripe cannot have their amount changed after creation; to change pricing you create a new Price. Assign lookup keys (such as pro_monthly) and resolve them at runtime so price changes do not require code deploys, and keep existing customers on legacy prices until you decide to migrate them.

Seats and Usage-Based Pricing

For per-seat billing, update the subscription item quantity when seats change. For usage-based billing, Stripe supports metered prices backed by Billing Meters: your application sends meter events as usage occurs and Stripe aggregates them into the invoice. Send usage from a reliable background process, not inline in user requests.

Checkout and the Customer Portal: Build Less, Ship Faster

For most SaaS products, the fastest and safest path is to let Stripe host the payment and self-service screens.

Stripe Checkout for Sign-Up and Upgrades

Create a Checkout Session in subscription mode with the selected Price, the existing Customer ID and success and cancel URLs, then redirect the user. Checkout handles card entry, Strong Customer Authentication where required, wallets such as Apple Pay and Google Pay, promotion codes, trials and tax collection. Because card details are entered on Stripe-hosted pages, your PCI DSS scope stays minimal. Do not grant access based on the redirect to your success URL; wait for the webhook confirming the subscription.

The Customer Portal for Self-Service

The Stripe Customer Portal lets customers update payment methods, download invoices, switch plans and cancel, all configured in the Stripe Dashboard. Your application only creates a portal session and redirects. This removes an entire category of billing support requests and is one reason billing fits comfortably inside a 12-week SaaS MVP build.

Trials, Free Plans and Entitlements

Decide early whether trials require a payment method. Card-required trials convert fewer sign-ups but more of them become paying customers; no-card trials do the opposite. Stripe supports both, including ending a trial gracefully when no payment method was added. Keep free plans as real subscriptions to a zero-price Price so every account follows the same code path. Finally, separate entitlements (what an account can do) from billing objects: map each plan to a set of features and limits in your application or with Stripe's Entitlements feature, and check entitlements in code instead of scattering plan-name comparisons across the codebase.

Why Webhooks Must Be Your Billing Source of Truth

Subscription state changes happen outside your application: renewals, failed renewals, portal cancellations, disputes and changes made by your team in the Dashboard. Webhooks are how your system learns about them, so treat webhook events as the authoritative input for access control and entitlements.

Events Every SaaS Should Handle

At minimum, handle checkout.session.completed, customer.subscription.created, customer.subscription.updated, customer.subscription.deleted, invoice.paid and invoice.payment_failed. Add customer.subscription.trial_will_end if you run trials, so you can remind users before the first charge. Derive access from the subscription status (active, trialing, past_due, canceled, unpaid and so on) rather than from individual payment events.

Verify, Deduplicate and Process Asynchronously

Verify every webhook signature using the Stripe-Signature header, your endpoint secret and the raw request body (most frameworks need explicit configuration to preserve it). Stripe can deliver the same event more than once and does not guarantee ordering, so store processed event IDs to skip duplicates and, when in doubt, fetch the latest subscription object from the API instead of trusting the order of arrival. Return a 2xx response quickly and do the actual work in a background job; Stripe retries failed deliveries, but slow handlers cause timeouts and noisy retries. This is a classic event-driven pattern, and our post on event-driven architecture covers the queueing and retry design behind it.

Handling Upgrades, Downgrades and Proration

Plan changes are where billing logic gets subtle. When a customer upgrades mid-cycle, Stripe can calculate prorations: a credit for unused time on the old price and a charge for the remaining time on the new one. You control this with the proration_behavior parameter, which can create prorations to appear on the next invoice, invoice them immediately with always_invoice, or skip them with none. A common SaaS policy is to upgrade immediately with an immediate prorated charge, so revenue and access change together, and to schedule downgrades for the end of the current period so customers keep what they paid for. Subscription Schedules let you model those future-dated changes cleanly. Whatever policy you choose, show customers a preview before they confirm; Stripe can generate an upcoming invoice preview so the amount you display matches what will be charged.

Failed Payments, Dunning and Revenue Recovery

Involuntary churn from failed payments is one of the most fixable revenue leaks in SaaS. Stripe Billing includes Smart Retries, which retry failed payments at times more likely to succeed, configurable retry schedules, automatic emails asking customers to update their card, and the card account updater that refreshes many expired or reissued cards automatically. On your side, decide what happens while a subscription is past_due: most products keep access during a short grace period, show an in-app banner linking to the Customer Portal and restrict access only after retries are exhausted and the subscription moves to canceled or unpaid. Make these rules explicit and test them, because ambiguity here leads either to lost revenue or to customers locked out over a temporary card issue.

Sales Tax, VAT and Stripe Tax

Software-as-a-service is taxable in many US states and in most countries that levy VAT or GST, and the rules differ by location and customer type. Stripe Tax calculates and collects the correct tax on subscriptions, invoices and Checkout Sessions when you enable automatic tax, using the customer's address and, for B2B sales, tax IDs where reverse charge applies. It also monitors where your sales are approaching registration thresholds. Stripe Tax does not register your business for you by default or replace an accountant; you still need to register in jurisdictions where you have obligations and file returns, though Stripe offers filing support through partners. Collect billing addresses at checkout from the start, since retrofitting address collection for existing customers is painful.

Reliability Practices: Idempotency, Testing and Reconciliation

Billing code deserves the same rigor as any financial system, even in an early-stage product.

Use Idempotency Keys on Every Write

Send an Idempotency-Key header with POST requests that create or modify billing objects. If a network error or timeout causes a retry, Stripe returns the original result instead of creating a second customer, subscription or charge. Derive keys from your own operation IDs, such as the ID of the upgrade request, so retries reuse the same key.

Test with the Stripe CLI and Test Clocks

Use test mode for all development, the Stripe CLI to forward webhook events to your local environment, and test clocks to simulate trials ending, renewals and failed payments months into the future without waiting. Automate tests for your entitlement logic against these scenarios.

Reconcile and Monitor

Run a scheduled job that compares subscription status in your database with Stripe and flags mismatches, and alert on webhook failures in the Dashboard. These checks catch missed events before customers or your finance team do. If you need help designing billing for a complex pricing model, our SaaS product engineering services cover billing architecture, migrations from legacy systems and reporting.

SaaS Subscription Billing with Stripe: Best Practices