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.

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.

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

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.
  • Metered prices (kind: 'metered') charge per unit of usage: Metered 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. To take features from Stripe instead: 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:
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.

{
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:

{
"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:

// 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:

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 modeAfter sign-up
Personal billing on (ENABLE_PERSONAL_ACCOUNT_BILLING=true)the billing page
hybrid or organizations-only, personal billing offcreate an organization, then its billing page (in hybrid they can skip with "Not now")
personal-only, personal billing off, or billing offplain 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.