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-onlyThe active organization
hybridThe active organization; the user's own account in personal context only with ENABLE_PERSONAL_ACCOUNT_BILLING=true
personal-onlyThe 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

PartLocationPage
Stripe keys and price idsapps/web/.env locally, Worker secrets in productionSetup, Go Live
Products, plans, limits, features, trialsapps/web/config/billing.config.tsPlans
Price env keysapps/web/env.ts and apps/web/env.examplePlans
Plan copyapps/web/messages/<locale>/billing.jsonPlans
Gating in loaders and actionsgetBilling({ c }) from apps/web/lib/billing.server.tsGating
Billing page (yours to restyle)apps/web/pages/(app)/settings/billing.tsxPlans
Public pricing page (yours)apps/web/pages/(marketing)/pricing.tsxPlans
Hooks on billing eventsapps/web/config/billing-hooks.config.server.tsHooks
Cancel, keep, delete, trials, failed paymentsonDelete and checkout in the billing configCancellations
Features from Stripe Entitlementsentitlements: 'stripe' in the billing configEntitlements
Kit code (don't edit)packages/billing/ (@kit/billing)

How a Subscription Flows

  1. 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.
  2. Stripe calls the webhook (/api/auth/stripe/webhook). Better Auth verifies the signature and writes the subscription row.
  3. The kit's lifecycle job (a background outbox job) re-reads the subscription from Stripe, corrects the row, and runs your hooks.
  4. 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).

Checkout returns the browser to billing while signed webhooks synchronize subscription state. Protected actions check current billing state.Click to expand

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