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

  1. 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, keys stripe_customer_id and value) 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 event in the logs) and is never billed. pnpm billing:doctor checks the test account; in production, watch for that log line.

  2. 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_VERSION in packages/billing/src/stripe-client.ts), so event payloads have the shape the code reads.
    • Events, exactly these five:
      • checkout.session.completed
      • customer.subscription.created
      • customer.subscription.updated
      • customer.subscription.deleted
      • entitlements.active_entitlement_summary.updated (needed only with entitlements: 'stripe'; harmless otherwise)

    Copy the endpoint's signing secret (whsec_…). It is not the one stripe listen printed.

  3. 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).

  4. 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 plan
    pnpm --filter web exec void secret put STRIPE_PRICE_PRO_YEARLY
    pnpm --filter web exec void secret put STRIPE_PRICE_STARTER_MONTHLY # and the rest of your plans
    pnpm --filter web exec void secret put STRIPE_PRICE_STARTER_YEARLY

    Set both Stripe keys and every price key together: with keys but a missing price, every billing request fails naming the plan and the key.

  5. Checkout options. If you turned on automaticTax, set up Stripe Tax in live mode first; Checkout fails without it.

  6. Deploy, then make a first real payment on your own organization and check:

    • The webhook endpoint's log in Stripe shows 200 for each event.
    • /settings/billing names the plan, and "Manage billing" opens the portal.
    • Refund it from the Stripe Dashboard if you like.

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 --live

Never 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.