# Setting Up Stripe Locally

> Turn billing on in development: Stripe test keys, products and prices, webhook forwarding with the Stripe CLI, the customer portal, and a first test checkout.

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

---

Everything here runs in Stripe's **test mode**: no real money moves. You need a Stripe account (a sandbox is fine). The Stripe CLI comes with the kit (`pnpm install`).

## The Quick Way: Three Commands

```bash
pnpm stripe login     # once: approve the pairing in the browser
pnpm billing:setup    # products, prices, customer portal and apps/web/.env
pnpm billing:dev      # the app plus webhook forwarding
```

`billing:setup` reads `apps/web/config/billing.config.ts` and asks before each step:

1. **Products and prices**: one Stripe price per line item, at exactly the config's `cost`, tagged with a kit lookup key (`kit:pro-monthly`) so re-runs reuse it. A price that differs from the config is never reused: a new one is created and the reason shown.
2. **Customer portal**: switching between the plans with a single price (a plan with several line items is switched in the app, [Metered Usage](./usage)), invoices, card updates and cancel at the end of the billing period (no proration), shown as a list of changes first. Your other settings stay. A brand-new account has no portal yet: setup sends you a link to click **Save** once, then continues.
3. **`apps/web/.env`**: the price ids and the webhook secret, other lines untouched, as a masked diff.
4. **`STRIPE_SECRET_KEY`**: kept if set; otherwise it asks for your test secret key (hidden as you type), or tells you where to add it.

Then prove it: `pnpm billing:setup --verify` pays with Stripe's test card on real Checkout, waits for the webhook, switches plan and opens the portal.

- **Anything wrong?** `pnpm billing:doctor` checks every piece (read-only) and says what to fix, who fixes it, and where.
- **Changed your plans?** Run `pnpm billing:setup` again: new prices and the portal list follow your config.
- **Which account:** the test key in `apps/web/.env` when it's set (the account the app uses), else your `stripe login`.
- **Live mode** is refused: live keys never go in `.env`.

### For Coding Agents

Every command answers JSON with `--json`: `status` (`done`, `needs-human`, `refused`, `failed`, also the exit code 0/2/3/1), the steps or checks, `nextSteps` (each with `actor`: `agent` or `human`, plain-language `instructions`, a `url`, and `resumeWith`: the command to run after) and a `summary` to tell the person.

1. `pnpm billing:doctor --json`: what's missing.
2. `pnpm billing:setup --plan --json`: what would change, without changing anything. Show it to the person.
3. `pnpm billing:setup --yes --json`: apply it. A step that needs the person (log in, add the key to `.env`) comes back as `needs-human` with the link: relay it, then run its `resumeWith`.
4. `pnpm billing:setup --verify --json`: the proof.

Tell the person in plain words, for example: "Billing is on in Stripe test mode on your account <name>. No real money moved. The automated test paid with Stripe's test card and the plan activated. Try it at localhost:5173 → Settings → Billing with card 4242 4242 4242 4242."

Over MCP it's one tool, `kit_billing_setup`: `mode` `check` (what `billing:doctor` shows), `plan` or `apply`, and `step` for one step. Its checks are also part of `kit_doctor` (ids `billing-setup.*`).

The steps, in order: `stripe` (which account, test mode only), `prices`, `portal-default` (you turn the customer portal on once), `portal`, `meters` (your usage meters match `billing.config.ts`), `dead-jobs` (no dead usage or subscription-update jobs), `env`, `key`, plus two that run only when named: `verify` (the proof) and `listen` (webhook forwarding in the background; `--stop --step listen` ends it). Without a terminal, a step that changes something asks first unless `--yes` is given: the result hands back the question with its `resumeWith`. `--step <id>` narrows it to one step (still with `--yes` to apply); `--verify` is `--step verify`, run once the rest is set up. With `--json`, test output and prompts go to stderr, so stdout is one JSON document. Agents with the Stripe MCP server can use it to inspect the sandbox while debugging; setup doesn't need it.

## Manual Setup

The same steps by hand, in the Dashboard.

### 1. Create the Products and Prices

In the Stripe Dashboard (test mode), **Product catalog → Add product** for each paid product in `apps/web/config/billing.config.ts`. The kit ships **Starter** and **Pro**, each with a monthly and a yearly plan (see the config for their prices; the amounts below are Pro's):

- Add a recurring price per plan: **19.00 USD monthly** and **190.00 USD yearly**.
- Copy each price id (`price_…`).

The amounts must match each plan's `cost` in the config: `cost` is what your pages show, the Stripe price is what customers pay ([Plans](./plans#prices)).

### 2. Set the Keys

In `apps/web/.env`:

```bash
STRIPE_SECRET_KEY=sk_test_...          # Developers → API keys → Secret key
STRIPE_PRICE_PRO_MONTHLY=price_...     # one key per plan (env.ts)
STRIPE_PRICE_PRO_YEARLY=price_...
STRIPE_PRICE_STARTER_MONTHLY=price_...  # and the rest of the config's plans
STRIPE_PRICE_STARTER_YEARLY=price_...
```

`STRIPE_WEBHOOK_SECRET` comes from the next step: don't restart `pnpm dev` until it's set. Billing turns on only with **both** Stripe keys; with exactly one, every request answers 500 and the log says `Billing needs STRIPE_WEBHOOK_SECRET (set both Stripe keys, or neither)` (or the other key's name).

### 3. Forward Webhooks

Stripe sends subscription changes to the app's webhook. Locally, the Stripe CLI forwards them:

```bash
pnpm stripe listen \
  --forward-to localhost:5173/api/auth/stripe/webhook \
  --events checkout.session.completed,customer.subscription.created,customer.subscription.updated,customer.subscription.deleted,entitlements.active_entitlement_summary.updated \
  --latest
```

It prints `Your webhook signing secret is whsec_…`. Put it in `apps/web/.env`, then restart `pnpm dev`:

```bash
STRIPE_WEBHOOK_SECRET=whsec_...
```

`pnpm stripe:listen` runs the same command (port 5173). `kit_billing_setup {mode: apply, step: listen}` also checks the secret in `.env` matches.

Keep `stripe listen` running while you test. The secret stays the same across runs on one machine.

`--latest` forwards events in Stripe's latest API version, which the kit pins (**`2026-10-28.endive`**). Without it they come in your account's default version, which on an older account has another shape.

### 4. Turn On the Customer Portal

Plan switches and "Manage billing" use Stripe's customer portal. In the Dashboard (test mode), **Settings → Billing → Customer portal**:

- Activate the portal.
- Under **Subscriptions**, turn on **Customers can switch plans** and add every product with every price your config offers.
- Under **Cancellations**, turn on cancelling, **At the end of the billing period**, no proration. `pnpm billing:doctor` flags any other setting.
- Choose what else customers may do there (update payment methods, invoices). The portal lets anyone with `billing:update` do whatever you enable here, once the account has checked out once ("Manage billing" needs a Stripe customer).

Proration for switches is set on the same page, not in the kit.

### 5. Try a Checkout

1. `pnpm dev`, sign up (or sign in as a seed user, e.g. `user1@makerkit.dev` / `testingpassword` after `pnpm db:seed`), and create an organization from the account switcher.
2. Go to **Settings → Billing** (`/settings/billing`) and choose a plan.
3. On Stripe Checkout, pay with `4242 4242 4242 4242`, any future date and any CVC.
4. Back on the billing page, "Payment received. Activating your plan…" shows. Reload once `stripe listen` shows the events with `[200]`: the plan card names your plan.

`pro-monthly` has a 14-day trial, so Checkout charges $0 today and the row's status is `trialing`. Pick `pro-yearly` to see an immediate charge.

The `stripe listen` terminal shows each event with `[200]`. Then check the row:

```bash
pnpm --filter web exec void db execute "select plan, status, reference_id from subscription"
```

## Without Stripe

To test gating without a Stripe account, any `sk_test_…` / `whsec_…` values and a `price_…` id per plan turn billing on: `getBilling` reads plans from your rows, so `pnpm db:seed` puts `user5@makerkit.dev` on the first paid plan, personally and as the owner of "Acme Paid". Gating works; Stripe actions don't: a new account's Checkout answers "Billing is unavailable", user5's plan switch answers "There's no subscription to switch anymore" (the seeded rows have no Stripe ids), and "Manage billing" doesn't show (no Stripe customer).

Next: [define your plans](./plans), then [gate features](./gating).
