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

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

---

`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

```ts
// pages/(app)/projects.server.ts
import { 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, where `count` is how many exist now. `limit: null` is unlimited; a limit neither the plan nor the defaults set is `0`, so a typo never opens anything.
- `toProps()`: `{ plan, enabled, features, limits }` for the page. Return it, never `billing` itself.
- `account`: `{ kind, id }`. Count usage against `billing.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:

```ts
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)` throws `UPGRADE_REQUIRED` without the feature.
- `requirePlanLimit({ limit, count })` throws `LIMIT_REACHED` when 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:

```tsx
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.

```ts
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](./setup#without-stripe).
