Billing
Stripe subscriptions for organizations and personal accounts: hosted Checkout and portal, a typed plans config, feature and limit gating, webhook sync and lifecycle hooks.
The kit bills with Stripe through Better Auth's Stripe plugin, wrapped by @kit/billing. Payment pages are Stripe's (Checkout and the customer portal), so no card data touches your app. You define plans in one config file, gate features and limits with one call, and react to billing events with hooks.
Billing is off when neither Stripe key is set, and on with both (with only one, every request fails naming the missing key). With it off, every account gets your config's default plan (defaultLimits and defaultFeatures), the billing page and its nav entry don't exist, and no Stripe call is made. A fresh clone runs without Stripe.
Who Is Billed
Account mode (ACCOUNT_MODE) | Billed account |
|---|---|
organizations-only | The active organization |
hybrid | The active organization; the user's own account in personal context only with ENABLE_PERSONAL_ACCOUNT_BILLING=true |
personal-only | The user (needs ENABLE_PERSONAL_ACCOUNT_BILLING=true) |
The account always comes from the session, never from the request. In an organization, members' billing permissions decide what they can do: billing:read sees /settings/billing (every member by default), billing:create starts a subscription, and billing:update switches plans and opens the Stripe portal (Roles and Permissions).
What's Where
| Part | Location | Page |
|---|---|---|
| Stripe keys and price ids | apps/web/.env locally, Worker secrets in production | Setup, Go Live |
| Products, plans, limits, features, trials | apps/web/config/billing.config.ts | Plans |
| Price env keys | apps/web/env.ts and apps/web/env.example | Plans |
| Plan copy | apps/web/messages/<locale>/billing.json | Plans |
| Gating in loaders and actions | getBilling({ c }) from apps/web/lib/billing.server.ts | Gating |
| Billing page (yours to restyle) | apps/web/pages/(app)/settings/billing.tsx | Plans |
| Public pricing page (yours) | apps/web/pages/(marketing)/pricing.tsx | Plans |
| Hooks on billing events | apps/web/config/billing-hooks.config.server.ts | Hooks |
| Cancel, keep, delete, trials, failed payments | onDelete and checkout in the billing config | Cancellations |
| Features from Stripe Entitlements | entitlements: 'stripe' in the billing config | Entitlements |
| Kit code (don't edit) | packages/billing/ (@kit/billing) |
How a Subscription Flows
- An owner or admin picks a plan on
/settings/billing. The kit checks the session's account and permissions, then sends them to Stripe Checkout. - Stripe calls the webhook (
/api/auth/stripe/webhook). Better Auth verifies the signature and writes thesubscriptionrow. - The kit's lifecycle job (a background outbox job) re-reads the subscription from Stripe, corrects the row, and runs your hooks.
getBilling({ c })now returns the paid plan: its features and limits apply on the next request.
Plan switches go through Stripe's confirm page (plans with extra or usage line items through the app's own review step, Metered Usage) and the portal handles cards, invoices and billing details; both come back to /settings/billing. Cancelling goes through Stripe's cancel page and always ends at period end; deleting an organization cancels its subscription first (Cancellations).
The browser return and webhook delivery are independent. Returning from Checkout is not proof the plan is active; check webhook delivery if the page still shows the old plan (Troubleshooting).
The Rules in Short
- Plan names only. Forms post a plan name; price ids, quantities and return URLs are built on the server from config.
- The session decides the account. Never pass an id from the request to billing code; count usage against
billing.account.id. - Gate in the loader and the action. Hidden UI is not a defence: the action calls
requireFeature/requirePlanLimit. - No GET writes. Checkout, switch and portal are POST actions; a link's prefetch never starts a Stripe session.
- Hooks are at-least-once and unordered. Dedupe on
eventId; send emails as your own outbox jobs. - Never log Stripe payloads, emails or Checkout and portal URLs (the URLs are bearer links).