> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nozle.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Entitlements

> Check feature access, usage limits, and margin state with nozle.can().

```ts theme={null}
const check = await nozle.can('workspace_123', 'api_calls')

if (!check.allowed) {
  throw new Error(check.reason ?? 'Feature unavailable')
}
```

`can()` calls `GET /api/v1/can` with the customer, feature, and optional string metadata.

## Signature

```ts theme={null}
can(
  customerId: string,
  feature: string,
  metadata?: Record<string, string>,
): Promise<CanResult>
```

```ts theme={null}
const check = await nozle.can('workspace_123', 'model_access', {
  model: 'example-large-model',
  region: 'us-east',
})
```

## `CanResult`

| Field                     | Type       | Description                      |
| ------------------------- | ---------- | -------------------------------- |
| `allowed`                 | `boolean`  | Whether the request may proceed. |
| `reason`                  | `string?`  | Denial or decision reason.       |
| `used`                    | `number`   | Current measured usage.          |
| `limit`                   | `number?`  | Configured usage limit.          |
| `remaining`               | `number?`  | Remaining allowance.             |
| `overage`                 | `boolean?` | Whether usage is in overage.     |
| `cost_per_use_cents`      | `number`   | Computed unit cost.              |
| `revenue_per_use_cents`   | `number`   | Computed unit revenue.           |
| `margin_per_use_cents`    | `number`   | Unit margin.                     |
| `margin_percent`          | `number?`  | Margin percentage.               |
| `min_margin_percent`      | `number?`  | Configured margin floor.         |
| `margin_level`            | `string?`  | Margin classification.           |
| `margin_enforcement_mode` | `string?`  | Configured enforcement behavior. |
| `warning`                 | `string?`  | Non-blocking warning.            |

## HTTP handler pattern

```ts theme={null}
const check = await nozle.can(customerId, 'analytics')

if (!check.allowed) {
  return Response.json(
    {
      error: check.reason ?? 'upgrade_required',
      used: check.used,
      limit: check.limit,
      remaining: check.remaining,
    },
    { status: check.overage ? 429 : 403 },
  )
}

return runAnalyticsQuery()
```

## Authorization guidance

Perform entitlement checks on the trusted backend immediately before protected work. A React `FeatureGate` improves the interface but is not an authorization boundary.

`can()` checks entitlement and usage state; it does not reserve product credits. Use `usage.track()` for atomic credit-backed consumption.