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.
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
pnpm stripe login # once: approve the pairing in the browserpnpm billing:setup # products, prices, customer portal and apps/web/.envpnpm billing:dev # the app plus webhook forwardingbilling:setup reads apps/web/config/billing.config.ts and asks before each step:
- 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. - Customer portal: switching between the plans with a single price (a plan with several line items is switched in the app, Metered 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.
apps/web/.env: the price ids and the webhook secret, other lines untouched, as a masked diff.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:doctorchecks every piece (read-only) and says what to fix, who fixes it, and where. - Changed your plans? Run
pnpm billing:setupagain: new prices and the portal list follow your config. - Which account: the test key in
apps/web/.envwhen it's set (the account the app uses), else yourstripe 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.
pnpm billing:doctor --json: what's missing.pnpm billing:setup --plan --json: what would change, without changing anything. Show it to the person.pnpm billing:setup --yes --json: apply it. A step that needs the person (log in, add the key to.env) comes back asneeds-humanwith the link: relay it, then run itsresumeWith.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).
2. Set the Keys
In apps/web/.env:
STRIPE_SECRET_KEY=sk_test_... # Developers → API keys → Secret keySTRIPE_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 plansSTRIPE_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:
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 \ --latestIt prints Your webhook signing secret is whsec_…. Put it in apps/web/.env, then restart pnpm dev:
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:doctorflags any other setting. - Choose what else customers may do there (update payment methods, invoices). The portal lets anyone with
billing:updatedo 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
pnpm dev, sign up (or sign in as a seed user, e.g.user1@makerkit.dev/testingpasswordafterpnpm db:seed), and create an organization from the account switcher.- Go to Settings → Billing (
/settings/billing) and choose a plan. - On Stripe Checkout, pay with
4242 4242 4242 4242, any future date and any CVC. - Back on the billing page, "Payment received. Activating your plan…" shows. Reload once
stripe listenshows 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:
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, then gate features.