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:
- Declare the key in
apps/web/env.ts(STRIPE_PRICE_TEAM_MONTHLY: string().optional()) and list it inapps/web/env.example. - Set it in
apps/web/.envlocally 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:setupplans no price for them; you make the Stripe meter and price by hand. - Seats are not supported in this version.
Limits and Features
limitsmaps a limit name to a maximum (nullis unlimited). A limit named like a meter is that meter's usage cap. A plan's limits are laid overdefaultLimits, 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 indefaultLimits, so free accounts have a value too.featuresare keys your code checks (hasFeature('export')), not copy. Accounts without a subscription getdefaultFeatures.gatingStatuses(default['active', 'trialing', 'past_due']): which Stripe statuses count as paid.past_duekeeps 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/pricingpage can't know who's visiting, so it still shows it, as a line in the card's highlights).checkouttoggles, 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:
apps/web/config/billing.config.ts: products, plans (names, intervals,cost), limits, features, trials.apps/web/env.tsandapps/web/env.example: oneSTRIPE_PRICE_*key per line item.apps/web/messages/<locale>/billing.json: product names, descriptions, highlights (agents: theapp_translations_*MCP tools).pnpm billing:setup: creates the Stripe prices at yourcost, updates the portal's switch list and writes the new price ids toapps/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: trueon 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 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.