Troubleshooting Billing

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

The Webhook Answers 400

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

CauseFix
Wrong signing secret: the 400 body says Failed to construct Stripe event, and the server log has Stripe's signature errorSet 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). 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).

"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):

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