# Products and Plans

> Define products and plans in billing.config.ts: prices from env keys, limits and features, trials, Checkout options, free products, renaming and retiring plans, and the billing and pricing pages.

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

---

Your products and plans live in `apps/web/config/billing.config.ts`. It's client-safe: copy is message keys, prices are env key **names**. Everything wrong with it is reported at once, naming the plan and the env key, never a value.

```ts
import { defineBillingConfig } from '@kit/billing/config';

export const billingConfig = defineBillingConfig({
  currency: 'usd',
  // what every account without a subscription gets
  defaultLimits: { projects: 3 },
  defaultFeatures: [],
  products: [
    {
      id: 'pro',
      name: 'billing.products.pro.name',
      description: 'billing.products.pro.description',
      highlights: ['billing.products.pro.highlights.projects'],
      badge: 'billing.products.pro.badge',
      highlighted: true,
      plans: [
        {
          name: 'pro-monthly',
          interval: 'month',
          lineItems: [
            { kind: 'flat', priceEnv: 'STRIPE_PRICE_PRO_MONTHLY', cost: 19 },
          ],
          limits: { projects: null }, // null: unlimited
          features: ['export'],
          freeTrial: { days: 14 },
        },
      ],
    },
  ],
});
```

A **product** is a card on the pricing table; a **plan** is one of its prices (`month` or `year`). Plan names are what forms post and what subscription rows store: lowercase letters, digits and dashes, unique across products, and distinct from every product id (one namespace).

## Prices

Each line item names an env key (`priceEnv`) that holds the Stripe price id for that environment, so test and live ids differ per deploy without code changes:

1. Declare the key in `apps/web/env.ts` (`STRIPE_PRICE_TEAM_MONTHLY: string().optional()`) and list it in `apps/web/env.example`.
2. Set it in `apps/web/.env` locally and as a Worker secret in production ([Go Live](./go-live)).

While billing is on, every plan's keys must be set to a `price_…` id, or every billing request fails naming the plan and the key. `cost` is the display price in `currency`: keep it equal to the Stripe price (Stripe charges its price, your pages show `cost`).

- **Several line items:** a plan can charge more than one flat price per checkout; the first line item identifies the plan in webhooks unless you set `primaryPriceEnv`. Two plans never share a line item's price.
- **Extra line items** reach Checkout with the plan. Switching to or from a plan that has any goes through the app's own review step (**Review switch** on the plan picker, then **Confirm change**) instead of Stripe's confirm page, which can't move several items: [Metered Usage](./usage).
- **Metered prices** (`kind: 'metered'`) charge per unit of usage: [Metered Usage](./usage). `billing:setup` plans no price for them; you make the Stripe meter and price by hand.
- **Seats** are not supported in this version.

## Limits and Features

- `limits` maps a limit name to a maximum (`null` is unlimited). A limit named like a meter is that meter's usage cap. A plan's limits are laid over `defaultLimits`, so a plan that bills a meter with a default cap must set its own (`null`: no cap); the config refuses it otherwise. A meter with no default and no plan limit is uncapped. Every limit a plan sets must also be in `defaultLimits`, so free accounts have a value too.
- `features` are keys your code checks (`hasFeature('export')`), not copy. Accounts without a subscription get `defaultFeatures`.

- `gatingStatuses` (default `['active', 'trialing', 'past_due']`): which Stripe statuses count as paid. `past_due` keeps access while Stripe retries the card; other statuses get the default plan.

Limits and features are typed from this file: a misspelled key in `hasFeature` or `checkPlanLimit` doesn't compile. Using them: [Gating](./gating). To take features from Stripe instead: [Entitlements](./entitlements).

## Trials and Checkout Options

- `freeTrial: { days: 14 }` on a plan starts a trial at checkout, **once per account across plans**: an account that had any trial pays at once, and the billing page's picker hides its trial line (the public `/pricing` page can't know who's visiting, so it still shows it, as a line in the card's highlights).
- `checkout` toggles, all off by default:

```ts
checkout: {
  promotionCodes: true,   // a promotion code field on Checkout
  automaticTax: true,     // needs Stripe Tax set up
  taxIdCollection: true,  // business tax ids
  trialWithoutCard: true, // trial starts without a card; no card by its end cancels it
},
```

## Free and Custom-Priced Products

A product with `plans: []` is free: shown in every interval, never checked out. What it describes is `defaultLimits` / `defaultFeatures`, which every account without a subscription gets.

Add `priceLabel` to make a plan-less product **custom-priced** instead, like an Enterprise tier: it shows the label ("Custom") where the price goes, its button says "Contact sales" and follows `ctaHref` on both the pricing and billing pages, and it's never the free plan. It needs a `ctaHref` (the config fails to load without one), and its line under the price label is the message `billing.products.<id>.billedAt`.

```ts
{
  id: 'enterprise',
  name: 'billing.products.enterprise.name',
  description: 'billing.products.enterprise.description',
  priceLabel: 'billing.products.enterprise.price', // "Custom"
  ctaHref: 'mailto:sales@your-company.com',       // or '/contact', or an https URL
  plans: [],
}
```

## Copy

`name`, `description`, `highlights`, `badge` (and `ctaLabel`) are message keys, in `apps/web/messages/<locale>/billing.json`:

```json
{
  "products": {
    "pro": {
      "name": "Pro",
      "description": "For teams that ship every week.",
      "highlights": { "projects": "Unlimited projects" },
      "badge": "Popular"
    }
  }
}
```

## Make It Your Pricing (Before Launch)

Before anyone pays, renaming is free. To replace the sample Pro plan with yours:

1. `apps/web/config/billing.config.ts`: products, plans (names, intervals, `cost`), limits, features, trials.
2. `apps/web/env.ts` and `apps/web/env.example`: one `STRIPE_PRICE_*` key per line item.
3. `apps/web/messages/<locale>/billing.json`: product names, descriptions, highlights (agents: the `app_translations_*` MCP tools).
4. `pnpm billing:setup`: creates the Stripe prices at your `cost`, updates the portal's switch list and writes the new price ids to `apps/web/.env`.

Then prove it: `E2E_BILLING=required pnpm --filter e2e test:billing` (the specs follow your config). The rules below matter once someone pays.

## Changing Plans Safely

- **Retire a plan:** keep it in the config and set `hidden: true` on its product. Subscribers keep it (their page still names it); nobody new can pick it. Add the replacement as a new product or plan.
- **Rename a plan:** subscription rows also store their Stripe price ids, so a renamed plan still resolves by price. Don't rename and change its price in one deploy: rows written before their next Stripe event have no price ids yet and would drop to the default plan.
- **New price for an existing plan:** point its env key at the new price id. Current subscribers keep their old price and keep their plan by name.
- **Removing a plan** with live subscribers shows them "Your subscription" with the default plan's limits: retire it instead.

## The Billing Page

`/settings/billing` (`apps/web/pages/(app)/settings/billing.tsx`) is yours to restyle. It shows the current plan with "Manage billing" (the Stripe portal) for members with `billing:update` once the account has a Stripe customer (after its first Checkout), and the plan picker: Checkout without a subscription, a confirm dialog then Stripe's confirm page with one. The components come from `@kit/billing/ui` (kit-owned; kit copy in the `subscription` namespace).

To start Checkout from your own page, post the same form:

```tsx
// your loader returns the account the form is for:
//   const billing = await getBilling({ c });
//   return { accountId: billing.account.id, billing: billing.toProps() };
import { CheckoutButton } from '@kit/billing/ui';

import { authPaths } from '#/config/auth-paths.ts';

<CheckoutButton
  action={`${authPaths.billing}?checkout`}
  referenceId={accountId}
  plan="pro-monthly"
/>
```

The billing page's plan cards are one component, `<PlanPicker />` (`@kit/billing/ui`): it chooses the button for each card from the account's state, so a page of your own can render it with `getPage`'s props. With a live subscription the plans start hidden behind a **Change plan** button (open straight away for a `?plan=` preselection or a switch under review), and a card gets `SwitchPlanButton` and `?switchPlan` (a confirm dialog, then Stripe's confirm page); a plan with extra or usage line items gets a **Review switch** link, then `SwitchReviewCard`. Posting `?checkout` with a live subscription switches it rather than starting a second one, and each new Checkout first expires the account's other open sessions. That expiry is best effort: two Checkouts started at the same instant, both paid, can still leave a second subscription to refund by hand.

It's a native form POST: the browser follows the redirect to Stripe, which a fetch-based form can't. Refusals come back to `/settings/billing` as a notice.

## The Pricing Page

`/pricing` (`apps/web/pages/(marketing)/pricing.tsx`) shows the same products, in config order, cached for every visitor. Each button goes to sign-up: the free plan first, upgrades from the billing page. A product's button follows its `ctaHref` (a site path, an https URL or a `mailto:` address; any other, like `//host` or `http://`, stops the config from loading) and its `ctaLabel`, as in the custom-priced example above.

### Straight to the Plan After Sign-Up

By default a paid card's button is plain sign-up: people start on the free plan and upgrade later. To take them from the plan they picked to paying for it, set `afterSignUp: 'billing'` in `billing.config.ts`:

```ts
export const billingConfig = defineBillingConfig({
  // ...
  afterSignUp: 'billing',
});
```

After sign-up (and email verification) they land on `/settings/billing?plan=<plan>` with that plan preselected, one click from Checkout. Where billing needs an organization, they create one first:

| Account mode | After sign-up |
|---|---|
| Personal billing on (`ENABLE_PERSONAL_ACCOUNT_BILLING=true`) | the billing page |
| `hybrid` or `organizations-only`, personal billing off | create an organization, then its billing page (in `hybrid` they can skip with "Not now") |
| `personal-only`, personal billing off, or billing off | plain sign-up |

Free and custom-priced cards, and cards with a `ctaHref`, are unchanged. The plan travels as a `next` path checked at every step, so it can only lead to a page of your site; an unknown plan name preselects nothing. `/pricing` is cached until the next deploy, so after changing the Stripe keys or `ENABLE_PERSONAL_ACCOUNT_BILLING`, deploy again for its buttons to follow.

A signed-in visitor with an organization open goes straight to that organization's billing page.
