Skip to main content
This guide is for contributors running the Bench web app on port 5173 and API on port 8080. Use a Stripe sandbox or test environment only. Never load a live payment key into the local launcher.

​
Update the Stripe CLI

For a Homebrew installation on macOS:
stripe upgrade is not a Stripe CLI command. Update it through the package manager used to install it. See the official Stripe CLI instructions.

​
Forward sandbox events

Authenticate the Stripe CLI to the same sandbox that owns your test products and prices:
The local endpoint is http://127.0.0.1:8080/api/billing/webhook. Keep the listener running. Use its whsec_... signing secret, not the secret from an unrelated Dashboard endpoint. These are snapshot events consumed by Bench’s billing handler. You do not need to enable every Stripe event. Finish stripe login in the browser before starting the listener. If login was canceled with Ctrl+C or credentials expired, run it again and use the new pairing link. Do not paste pairing links, secret keys or webhook signing secrets into tickets. Stripe cannot deliver directly to your machine’s localhost from a Dashboard webhook destination. For local development, use the CLI forwarding command. A deployed endpoint instead needs its own reachable HTTPS URL and signing secret. See Stripe webhook testing and the Stripe CLI.

​
Configure test prices

Create recurring EUR sandbox prices matching the local plan catalog: Use four distinct price IDs from the same sandbox as the API key. Annual cards show a rounded monthly equivalent; Checkout charges the annual price. Free has no Stripe price. In this development workspace, enter the values in the ignored .context/local-billing.env file:
Restart the local API after configuration changes, once active evaluations have finished. The workspace launcher accepts only test secret keys and passes billing configuration to the API, not Vite or the browser. It rejects partial configuration and duplicate price IDs. An unconfigured Checkout button stays disabled; a UI fixture passing does not mean Stripe is configured. For existing subscribers, configure the sandbox Customer Portal to allow the relevant subscription updates. Bench passes the selected price into the confirmation flow. Changing a plan is not an authorization to silently create a second subscription.

​
Verify the full flow

  1. Open Bench pricing, choose Monthly or Yearly, then select Builder or Growth.
  2. Confirm the plan, amount and billing interval on hosted Checkout before submitting.
  3. Use Stripe’s sandbox card 4242 4242 4242 4242, a future expiry and any three-digit CVC.
  4. Confirm the listener receives a successful webhook response and Bench refreshes the plan and allowance.
  5. Test a failed payment, duplicate event delivery and a subscription change in the sandbox.
  6. Review changes and prorations on the Customer Portal confirmation screen before submitting.
See Stripe testing for additional test payment methods. Do not use real card details. Account onboarding or expired CLI credentials must be resolved in Stripe; Bench cannot bypass account restrictions. Model-provider billing is independent. A working Stripe Checkout does not resolve an evaluation provider’s credit balance.