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

# Entitlements

> Check feature access from your server for secure feature gating.

## checkEntitlement

Check if a customer has access to a specific feature. Use this in API routes to enforce feature gates server-side.

```typescript theme={null}
const result = await billing.checkEntitlement("user_123", "api_calls");

if (!result.has_access) {
  return Response.json({ error: "Upgrade required" }, { status: 403 });
}

// For usage-based features, check the limit
if (result.usage !== null && result.limit !== null) {
  if (result.usage >= result.limit) {
    return Response.json({ error: "Usage limit exceeded" }, { status: 429 });
  }
}
```

### Parameters

| Name         | Type     | Description               |
| ------------ | -------- | ------------------------- |
| `customerId` | `string` | Customer external user ID |
| `featureKey` | `string` | Feature key to check      |

### Response

```typescript theme={null}
interface EntitlementResponse {
  feature_key: string
  has_access: boolean
  reason?: string          // Reason if access denied
  limit: number | null     // null for boolean features
  usage: number | null     // null for boolean features
  metadata: {
    remaining?: number
    resets_at?: string
    type?: string
  } | null
}
```

## Example: API middleware

```typescript theme={null}
// middleware/entitlement.ts
import { BillingOS } from "@billingos/node";

const billing = new BillingOS({ secretKey: process.env.BILLINGOS_SECRET_KEY! });

export async function checkFeatureAccess(userId: string, feature: string) {
  const entitlement = await billing.checkEntitlement(userId, feature);

  if (!entitlement.has_access) {
    throw new Error(`Feature "${feature}" requires a plan upgrade`);
  }

  return entitlement;
}
```

```typescript theme={null}
// In your API route
const entitlement = await checkFeatureAccess(userId, "api_calls");
// Proceed with the operation...
```

<Warning>
  Always enforce entitlements server-side for security-critical features. Client-side `FeatureGate` components improve UX but can be bypassed by determined users.
</Warning>