# Troubleshooting Billing

> Fixes for webhook 400s, a plan that doesn't activate, 'Billing is unavailable', missing price keys and the billing page's 404.

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

---

## The Webhook Answers 400

Stripe's webhook log (or the `stripe listen` terminal) shows `[400]`:

| Cause | Fix |
|---|---|
| Wrong signing secret: the 400 body says `Failed to construct Stripe event`, and the server log has Stripe's signature error | Set `STRIPE_WEBHOOK_SECRET` to the secret of **this** endpoint: `stripe listen`'s locally, the dashboard endpoint's in production. Test and live secrets differ. Restart `pnpm dev` after changing `.env`. |
| No `stripe-signature` header (`Stripe signature not found`) | Something other than Stripe is calling the URL, or a proxy strips headers. |
| Handling failed after verification: the log says `Stripe webhook failed. Error: …` | Better Auth's row write or the kit's job enqueue failed (usually the database). Stripe retries; check the server log and the database. |

## The Plan Doesn't Activate After Checkout

"Activating your plan…" stays on `/settings/billing`:

- **Locally:** `stripe listen` isn't running, or forwards to another port (the dev server moves to 5174 when 5173 is busy). Its terminal should show the events with `[200]`.
- **Two Stripe accounts:** `stripe listen` forwards the events of the account you logged into with `stripe login`, while the app uses `STRIPE_SECRET_KEY`'s account. If they differ, no event ever arrives. Run it with the app's key: `STRIPE_API_KEY=<your sk_test key> pnpm stripe listen …`, or log in to the same account.
- **In production:** the endpoint URL or events are wrong ([Go Live](./go-live)). The endpoint's log in Stripe shows each attempt.
- **The webhook says 200 but nothing changed:** the lifecycle job runs from the outbox; check for dead jobs ([Failures](../outbox/failures)).

## "Billing is unavailable right now"

A Stripe request failed or took over 10 seconds (each call has its own 10-second limit, with no retries). The server log names the plan and Stripe's error code, never its message:

- `billing: checkout failed`: Stripe refused the Checkout Session. Common codes: a price id from the other mode (test vs live), Stripe Tax not set up with `automaticTax` on.
- `billing: plan switch failed`: the Customer portal doesn't allow switching, or its **products** list doesn't include the plan's product with every price (Stripe: "the configuration does not include the price in its `features[subscription_update][products]`").
- `billing: portal failed`: the Customer portal isn't activated in this mode.
- `billing: guided switch refused by Stripe` (with a `code`): the in-app switch of a plan with extra or usage line items failed. The page shows `SWITCH_PAYMENT_FAILED` for a card that needs confirming or was declined, `BILLING_UNAVAILABLE` for anything else; `SWITCH_NOT_AVAILABLE` means the subscription no longer holds the old plan's prices (switched already, or a price changed since it started).
- `billing: open Checkout sessions not expired before a new one`: Stripe couldn't list or expire the customer's open sessions; the new Checkout went ahead.

## The App Fails Naming a Price Key

`plan "pro-monthly": STRIPE_PRICE_PRO_MONTHLY is not set` (or "is not a Stripe price id"): with both Stripe keys set, every plan needs its price key. Set it in `apps/web/.env` or as a Worker secret, or remove both Stripe keys to turn billing off.

## /settings/billing Is a 404

The page exists only where the account is billed ([Who Is Billed](./overview#who-is-billed)):

- Both Stripe keys must be set.
- In personal context, `ENABLE_PERSONAL_ACCOUNT_BILLING=true` is needed (except for a user who still pays after you turned it off: they keep a page with the portal, cancel and keep, and no plan changes).
- In an organization, the member needs `billing:read`.

## "There's no billing account yet"

Shown only when the portal was posted for an account without a Stripe customer, from a stale page: "Manage billing" appears after the account's first Checkout.

## The Plan Picker Refuses

- **"Your subscription has a payment problem"** (`SUBSCRIPTION_NEEDS_ATTENTION`): the subscription is `past_due`, `unpaid` or `paused`. Plan changes are blocked until the card is fixed in "Manage billing" (a change would start a second subscription).
- **"You're already on this plan"** (`ALREADY_ON_PLAN`): the posted plan is the current one.
- **"The organization changed in another tab"** (`REFERENCE_CHANGED`): the page was rendered for another account; reload.

## Running the Billing E2E Suite

`pnpm --filter e2e test:billing` runs Checkout, the trial, a plan switch and the portal against your Stripe **test mode**, with `stripe listen` and a billing-on preview on port 4181 started for you (`apps/e2e/playwright.billing.config.ts`). It needs `STRIPE_SECRET_KEY=sk_test_…` (shell or `apps/web/.env`) plus the products, prices and portal (`pnpm billing:setup`); the Stripe CLI is the kit's pinned one. `pnpm billing:setup --verify` runs it in required mode. Without them the specs are skipped with the reason, so `pnpm test:e2e` stays green. When the run is meant as proof, set `E2E_BILLING=required`: a missing prerequisite then fails it instead. The specs buy the plans in your `billing.config.ts` (a plan without a trial, one with a trial, two plans of one product for the switch) and skip the ones your config can't run. Each spec signs up its own organization, so your sandbox collects test customers and subscriptions.

The main e2e suite always runs with billing off, whatever `apps/web/.env` holds.

## A Member Can't Change the Plan

Starting a subscription needs `billing:create`; switching and the portal need `billing:update`. Owners and admins have both by default ([Roles and Permissions](../members-management/roles-permissions)).
