Billing and Stripe

Two modes

Demo mode is the default. Plan changes apply instantly, a demo invoice is recorded and nobody is charged. This lets you show the whole billing screen to customers or buyers with no setup.

Stripe mode turns on when STRIPE_SECRET_KEY is set. Upgrades open Stripe Checkout, and managing or cancelling opens the Stripe customer portal.

Switch on Stripe

1. In the Stripe dashboard, create two products, Growth and Scale, each with a monthly and a yearly recurring price
2. Add the four price ids to your environment:

1. Set STRIPE_SECRET_KEY to your secret key (start with a test key)
2. Add a webhook endpoint in Stripe pointing to https://YOUR-APP/api/billing/webhook for these events: checkout.session.completed, customer.subscription.updated, customer.subscription.deleted, invoice.paid and invoice.payment_failed
3. Copy the endpoint's signing secret into STRIPE_WEBHOOK_SECRET

Test with Stripe's test cards, then repeat with live keys when you are ready.

What the webhook does

Webhooks are verified with Stripe's signature scheme and refused if the signature is wrong or the timestamp is more than five minutes old. Each event id is recorded so a repeated delivery is ignored. A failed payment moves the workspace to Starter limits until it is fixed and notifies the owners.

Plan limits

Limits live in lib/plan-data.ts and are enforced by the API:

Going over a limit returns HTTP 402 with an upgrade message. A downgrade is refused while the workspace still holds more than the smaller plan allows, and the message lists exactly what to remove.

Invoices

Demo invoices and Stripe invoices appear together in the billing screen. Each demo invoice has a printable page you can save as a PDF.