Set up Stripe billing for a SaaS subscription

The single most consequential billing decision. Per-seat, flat monthly, usage-based, freemium, free trial, annual discounts: each combination implies different Stripe primitives (Subscriptions vs Usage Records vs Invoices) and different webhook events to handle. Decide before you write a line of integration code.

Every plan in your matrix needs a Product (the thing) + a Price (the cost). Don't create them by hand in the dashboard for production — write them in code and check in the IDs, so dev / staging / prod stay in sync. Use the Test mode for everything until you're ready to launch.

Two choices: Stripe Checkout (Stripe-hosted, fastest to ship, less customizable) or Stripe Elements (your-domain-hosted, fully custom, more code). For a 1-month-old startup: Checkout. For a product where the checkout is part of the product experience: Elements. Switch later if needed.

Webhooks are how Stripe tells your backend that 'subscription created / payment succeeded / payment failed.' The single biggest source of billing bugs in early SaaS is webhook handling: signatures fail silently in dev, the same event arrives 5 times, events arrive out of order, and the DB drifts from Stripe state. Build this carefully.

Read this codebase + the subscription model in the Brief and produce a Stripe webhook handler.

Output:
1. A POST /api/webhooks/stripe endpoint with signature verification using STRIPE_WEBHOOK_SECRET
2. Idempotency key check (use the event ID; if already processed, return 200 immediately)
3. A switch on event.type covering at minimum:
   - customer.subscription.created → write Subscription row, set user.plan
   - customer.subscription.updated → update Subscription row, update user.plan if changed
   - customer.subscription.deleted → mark Subscription canceled, set user.plan to free
   - invoice.paid → mark Invoice paid, extend access if needed
   - invoice.payment_failed → mark Invoice failed, trigger dunning email (step 8)
4. Each handler returns 200 quickly (under 5 seconds Stripe timeout); long work goes to a queue
5. Each handler logs the event ID + event type + the DB write performed

Output the handler code into the codebase. Add one row per event handler to the Webhook events surface.

The single most common production billing bug: Stripe says 'this customer is on Pro' and your DB says 'free.' Causes: webhook delivery delay, webhook handler bug, manual changes in the Stripe dashboard. Build a reconciliation job that runs nightly + a 'sync from Stripe' button on the user's account.

If you have customers in California, Texas, New York, the EU, the UK, Australia, or Canada (most likely all of them), you owe sales tax. Stripe Tax auto-calculates the right rate at checkout based on customer location + your nexus. The alternative (collecting tax IDs manually + filing returns yourself) is a nightmare. Spend the 0.5%.

Stripe Customer Portal is a hosted page where users update payment methods, change plans, view invoices, and cancel subscriptions. It saves you 2-3 weeks of UI work for the price of a slightly less branded experience. Use it; you can custom-build later.

When a card fails — expiration, insufficient funds, fraud block — Stripe retries on a schedule and emails the customer. The default schedule is reasonable but generic. For SaaS specifically, the right approach is: 3 retries over 21 days + 3 customer emails + grace period before downgrade. Configure it once; it recovers ~30-50% of failed payments.

Draft the dunning email sequence for this SaaS.

Output 3 emails:

1. Day 1 (payment failed) — friendly, factual: "we couldn't charge your card; we'll retry in 3 days; here's a link to update your payment method"
2. Day 7 (second retry failed) — slightly firmer: "the retry didn't go through; please update your card by [date] to avoid losing access"
3. Day 21 (final retry, about to be downgraded) — direct: "your card has failed 3 times; if it's not updated by [date] tomorrow, you'll be downgraded to the free plan; here's the update link"

Tone: warm but factual. No "URGENT!!!"; no scolding. Each email <100 words. Include the customer's plan, the failed amount, the next retry date, and a 1-click link to the customer portal.

Output to the Brief surface as a versioned dunning copy section.

Test mode → Live mode is mostly a config switch but has 5-10 things you'll forget. New API keys, new webhook endpoint + secret, new Product / Price IDs, business identity verification, payout schedule, business statement descriptor. Walk the checklist before you charge a real card.

Once live, billing failure modes get expensive fast. A failed webhook handler can mean 50 customers paid but didn't get access. Build observability: alerts on webhook failures, dashboards for MRR / churn / failed payments, weekly reconciliation reports. Stripe Sigma + your own metrics dashboard cover most cases.