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

*Canonical: https://makerkit.dev/docs/void-cloudflare/billing/go-live*

---

Stripe's test and live modes have separate products, prices, keys, webhooks and portal settings. Repeat the [setup](./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](./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](./setup#4-turn-on-the-customer-portal)). Then set Stripe's trial reminder and failed-payment emails and retries in live mode ([Cancellations](./cancellations)).

4. **Worker secrets.** From your machine ([Deploy to Production](../deployment/production)):

   ```bash
   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:

```bash
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.
