Gating Features and Limits
Check the plan in loaders, enforce it in actions with requireFeature and requirePlanLimit, show an upgrade prompt on the client, and test gated actions with fakeBilling.
getBilling({ c }) from apps/web/lib/billing.server.ts returns the plan of the session's account: the active organization, or the user in personal context. It never returns null: without a subscription, or with billing off, it's your config's default plan. No check calls Stripe or the database; the plan is read once per request.
In the Loader: Show What the Plan Allows
// pages/(app)/projects.server.tsimport { defineHandler, type InferProps } from 'void';import { getBilling } from '#/lib/billing.server.ts';export const loader = defineHandler(async (c) => { const billing = await getBilling({ c }); // the active organization's id, or the user's in personal context const projects = await listProjects({ accountId: billing.account.id }); return { projects, canAdd: billing.checkPlanLimit({ limit: 'projects', count: projects.length }), billing: billing.toProps(), // plain values for the page };});export type Props = InferProps<typeof loader>;hasFeature('export'): whether the plan has the feature.checkPlanLimit({ limit, count }):{ allowed, limit }for one more, wherecountis how many exist now.limit: nullis unlimited; a limit neither the plan nor the defaults set is0, so a typo never opens anything.toProps():{ plan, enabled, features, limits }for the page. Return it, neverbillingitself.account:{ kind, id }. Count usage againstbilling.account.id, never an id from the request.
In the page, hasFeature(props.billing, 'export') from @kit/billing reads the same features.
In the Action: Enforce It
Hidden buttons aren't a defence. Every action that uses a paid feature or adds a counted thing checks again:
export const actions = { create: defineHandler(async (c) => { const billing = await getBilling({ c }); const count = await countProjects({ accountId: billing.account.id }); billing.requirePlanLimit({ limit: 'projects', count }); return createProject({ accountId: billing.account.id /* … */ }); }),};requireFeature(key)throwsUPGRADE_REQUIREDwithout the feature.requirePlanLimit({ limit, count })throwsLIMIT_REACHEDwhen one more won't fit.
Both answer 409 { code, message, limit, upgradable }, with message already translated. upgradable is true only when billing is on for the account, so a paid plan can lift the refusal. Use the require* calls in actions only: in a loader, a refusal would fail the whole page.
On the Client: Show the Refusal
billingRefusalOf(error) from @kit/billing decodes a failed action into the refusal, or null for any other error:
import { billingRefusalOf } from '@kit/billing';const refusal = billingRefusalOf(form.error);{refusal && ( <Alert variant="destructive"> <AlertDescription> {refusal.message}{' '} {refusal.upgradable && <Link href={authPaths.billing}>{t('upgrade')}</Link>} </AlertDescription> </Alert>)}Offer the upgrade link only when upgradable is true: with billing off there's nothing to upgrade to.
Testing a Gated Action
Mock #/lib/billing.server.ts with fakeBilling from @kit/billing/testing: the real Billing object built from your config, so a misspelled key doesn't compile.
import { expect, it, vi } from 'vite-plus/test';import { UPGRADE_REQUIRED } from '@kit/billing';import { fakeBilling } from '@kit/billing/testing';import { billingConfig } from '#/config/billing.config.ts';import { getBilling } from '#/lib/billing.server.ts';vi.mock('#/lib/billing.server.ts', () => ({ getBilling: vi.fn() }));// `exportProjects` is your action, `c` a stub context (see the recipe test)it('refuses a free account the export', async () => { vi.mocked(getBilling).mockResolvedValue(fakeBilling({ config: billingConfig })); await expect(exportProjects({ c, count: 0 })).rejects.toMatchObject({ code: UPGRADE_REQUIRED, });});fakeBilling({ config, features: ['export'] }) grants features; a full working example is apps/web/lib/__tests__/billing.server.recipe.test.ts. To try paid gating in the running app, see Without Stripe.