Stripe Billing Integration: Plans & Webhooks

Subscription billing looks straightforward until webhooks fail silently, proration surprises finance, and customers end up with duplicate subscriptions after a card update.

This guide covers the integration path we use for SaaS MVPs, enough to charge reliably without over-engineering on day one.

Products, prices, and checkout

Model plans as Stripe Products with recurring Prices. Keep plan metadata (feature flags, limits) in your database keyed by price ID, not duplicated only in Stripe.

Stripe Checkout is fastest for MVP: hosted UI, SCA handling, and Apple Pay without custom PCI scope. Customer Portal covers self-serve plan changes when you are ready.

Webhooks are the source of truth

Never grant access solely from the client redirect after payment. Listen for checkout.session.completed, customer.subscription.updated, and invoice.payment_failed.

Verify webhook signatures, store raw events idempotently, and process asynchronously. Retry failures with alerting. Stripe will disable endpoints that fail consistently.

Common gotchas

Test clock and test cards for trial expiry, failed renewals, and 3D Secure flows before launch.

Handle past_due and canceled states in your app UI. Do not leave users in limbo with active sessions but inactive subscriptions.

Document how refunds and chargebacks map to entitlements so support has a playbook.