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

*Canonical: https://makerkit.dev/docs/void-cloudflare/billing/overview*

---

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](../members-management/roles-permissions)).

## What's Where

| Part | Location | Page |
|---|---|---|
| Stripe keys and price ids | `apps/web/.env` locally, Worker secrets in production | [Setup](./setup), [Go Live](./go-live) |
| Products, plans, limits, features, trials | `apps/web/config/billing.config.ts` | [Plans](./plans) |
| Price env keys | `apps/web/env.ts` and `apps/web/env.example` | [Plans](./plans#prices) |
| Plan copy | `apps/web/messages/<locale>/billing.json` | [Plans](./plans#copy) |
| Gating in loaders and actions | `getBilling({ c })` from `apps/web/lib/billing.server.ts` | [Gating](./gating) |
| Billing page (yours to restyle) | `apps/web/pages/(app)/settings/billing.tsx` | [Plans](./plans#the-billing-page) |
| Public pricing page (yours) | `apps/web/pages/(marketing)/pricing.tsx` | [Plans](./plans#the-pricing-page) |
| Hooks on billing events | `apps/web/config/billing-hooks.config.server.ts` | [Hooks](./hooks) |
| Cancel, keep, delete, trials, failed payments | `onDelete` and `checkout` in the billing config | [Cancellations](./cancellations) |
| Features from Stripe Entitlements | `entitlements: 'stripe'` in the billing config | [Entitlements](./entitlements) |
| 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](../outbox/overview)) 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](./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](./cancellations)).

{% img src="/assets/images/docs/void-cloudflare/billing-lifecycle.svg" width="600" height="1120" alt="Checkout returns the browser to billing while signed webhooks synchronize subscription state. Protected actions check current billing state." /%}

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](./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).
