Payments and subscriptions

Choose and test your payment service

Billing handles payments. Access permissions are stored separately as entitlements. Complete persisted account setup, then open /billing in the running Web app to see the plan interface. With BILLING_PROVIDER=local, you are exploring local behavior rather than collecting real money.

Choose one supported payment provider, follow its setup guide, create your own test product and price, and copy the named server settings into apps/web/.env.local. Save and restart the Web server. Complete one checkout using that provider's sandbox instructions, then inspect the workspace's access state after the provider's webhook arrives. A webhook is the provider's signed message to your server about a payment event.

A success page alone does not unlock features. If checkout completes but access remains inactive, check the provider's webhook delivery and your server's event processing before repeating payment. Test cancellation and expired access as well. Phone purchases use the separate RevenueCat/store setup, not this Web checkout.

• Choose a billing adapter and its settings
• Set your own products and prices
• Set up Stripe in a test environment

Web billing

The Web application supports the billing provider you select with BILLING_PROVIDER; Stripe is one option. Open /billing for Web plans and subscription management. Follow the selected provider's guide to set its server-only credentials, product or price IDs and webhook verification settings in the matching test or live environment.

Authorize through entitlements

A checkout redirect is not evidence of active access. The server-owned entitlement decides whether a workspace can use a paid capability. Check that entitlement at the action boundary even when the interface already hides the action.

Verify the lifecycle

Use sandbox events to verify activation, updates, cancellation, and webhook handling. Keep repeated events safe and ensure an inactive entitlement blocks paid operations. Native mobile purchases remain a separate RevenueCat integration boundary.

Setup and configuration

The plan catalog lives in src/product-plans.ts and drives the /billing surface and /choose-plan onboarding step. Billing is configured server-side with BILLING_PROVIDER=stripe, STRIPE_SECRET_KEY, the price ids for each plan and interval, and STRIPE_WEBHOOK_SECRET. Lemon Squeezy is available as an alternative adapter.

Seat-based plans use the editable seat steppers (src/seat-count.ts); the quantity travels with the checkout session so the billed seats match the workspace. Plans can also declare meteredUsage in src/product-plans.ts so the hourly billing.usage-report job reports usage_counter deltas to Stripe billing meters, while workspace owners set monthly AI budgets and hard per-meter ceilings under Settings → Usage (USAGE_METERS in src/usage-meters.ts).

Checkout: POST /api/billing/checkout
Portal:   POST /api/billing/portal
Webhook:  POST /api/billing/webhook  (signature-verified)

Implementation workflow

A checkout redirect is only a pending intent — access changes when the signed webhook lands and the server-owned entitlement updates. Gate paid actions with the entitlement check at the server boundary (entitlement-gate.tsx / entitlement-check.ts) even when the interface already hides them.

The customer portal handles plan changes, cancellation, and payment methods. Keep subscription state readable by workspace members and keep native mobile purchases behind the separate RevenueCat boundary.