Going Live with Stripe
The production checklist: live products and prices, the webhook endpoint with its exact events and API version, the customer portal, Worker secrets and a first real payment.
Stripe's test and live modes have separate products, prices, keys, webhooks and portal settings. Repeat the setup in live mode, with these production differences.
Checklist
Products and prices. Create them in live mode, with the same amounts as each plan's
cost. Live price ids differ from test ones. With metered usage (Metered Usage), also make each meter (same event name, Sum, keysstripe_customer_idandvalue) and its usage price in live mode before you deploy: usage recorded without the live meter dies in the outbox (billing: Stripe refused a usage eventin the logs) and is never billed.pnpm billing:doctorchecks the test account; in production, watch for that log line.Webhook endpoint. Developers → Webhooks → Add endpoint:
- URL:
https://<your-domain>/api/auth/stripe/webhook - API version:
2026-10-28.endive, the version the kit's Stripe client is pinned to (STRIPE_API_VERSIONinpackages/billing/src/stripe-client.ts), so event payloads have the shape the code reads. - Events, exactly these five:
checkout.session.completedcustomer.subscription.createdcustomer.subscription.updatedcustomer.subscription.deletedentitlements.active_entitlement_summary.updated(needed only withentitlements: 'stripe'; harmless otherwise)
Copy the endpoint's signing secret (
whsec_…). It is not the onestripe listenprinted.- URL:
Customer portal (live mode): activate it, turn on Customers can switch plans with every product and price you offer, set Cancel subscriptions to at the end of the billing period with no proration (the app's Cancel button uses it), and choose what else customers may do (Setup). Then set Stripe's trial reminder and failed-payment emails and retries in live mode (Cancellations).
Worker secrets. From your machine (Deploy to Production):
pnpm --filter web exec void secret put STRIPE_SECRET_KEY # sk_live_…pnpm --filter web exec void secret put STRIPE_WEBHOOK_SECRET # the endpoint's whsec_…pnpm --filter web exec void secret put STRIPE_PRICE_PRO_MONTHLY # one per planpnpm --filter web exec void secret put STRIPE_PRICE_PRO_YEARLYpnpm --filter web exec void secret put STRIPE_PRICE_STARTER_MONTHLY # and the rest of your planspnpm --filter web exec void secret put STRIPE_PRICE_STARTER_YEARLYSet both Stripe keys and every price key together: with keys but a missing price, every billing request fails naming the plan and the key.
Checkout options. If you turned on
automaticTax, set up Stripe Tax in live mode first; Checkout fails without it.Deploy, then make a first real payment on your own organization and check:
- The webhook endpoint's log in Stripe shows
200for each event. /settings/billingnames the plan, and "Manage billing" opens the portal.- Refund it from the Stripe Dashboard if you like.
- The webhook endpoint's log in Stripe shows
The kit adds Stripe's Checkout and portal origins to the CSP's form-action when billing is on; nothing to configure.
Checking Production
pnpm billing:doctor --live checks the live webhook endpoint (URL, the five events, the API version). Run it yourself, in your own terminal, with a read-only restricted live key (Developers → API keys → Create restricted key, "Webhook Endpoints: Read" only) and your production URL:
STRIPE_LIVE_API_KEY=rk_live_… SITE_URL=https://your-domain pnpm billing:doctor --liveNever paste a live key into chat or save it in apps/web/.env.
Changing the Stripe API Version
The API version moves with the stripe package. When you bump it, change STRIPE_API_VERSION and the webhook endpoint's API version together, in test mode first.