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

# Entitlements

# Entitlements & Feature Gating

Fype provides an **Entitlements Engine** that separates purchase details from client-side feature authorization.

***

## Core Entitlements Concept

Your application should never check if a customer has bought a specific "Monthly Plan" or "Yearly Plan." If you rename plans or change prices, you would have to redeploy your frontend.

Instead, your application checks if the customer has an active **Entitlement** (e.g., `premium_analytics`). Fype maps purchase events to these entitlements on the server.

```mermaid theme={null}
graph LR
    ActiveSub[Active Subscription] -->|Unlocks| Product[Product e.g., Pro Tier]
    Product -->|Linked to| Entitlement[Entitlement e.g., premium_analytics]
    AppCode[App Frontend Code] -->|Checks| Entitlement
```

***

## Verifying Customer Access

### 1. Retrieve Active Entitlements via API

To check which entitlements are active for a customer, query the entitlements endpoint:

* **Endpoint**: `GET /v1/subscriptions/customer/{customer_id}/entitlements`
* **Headers**: `Authorization: Bearer YOUR_API_KEY`

#### Example Response

```json theme={null}
{
  "customer_id": "d80b62e4-9d33-4f9e-a0e2-88229b4fb712",
  "active_entitlements": [
    "api_access",
    "advanced_reporting"
  ]
}
```

### 2. Verify Access using the Python SDK

The Fype SDK provides a convenience helper to check for a specific permission directly:

```python theme={null}
from fype import Fype

fype = Fype(api_key="fype_test_...")

# Check if customer has access to advanced analytics
has_access = fype.entitlements.check(
    customer_id="d80b62e4-9d33-4f9e-a0e2-88229b4fb712",
    entitlement_identifier="advanced_reporting"
)

if has_access:
    # Render premium charts
    pass
```

***

## Setup Guide

### 1. Create an Entitlement

Define a feature slug in the Fype catalog:

```bash theme={null}
curl -X POST https://api.fype.dev/v1/entitlements \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "api_access",
    "name": "Full API Access",
    "description": "Permits customers to run queries on our production API endpoints"
  }'
```

### 2. Link the Entitlement to a Product

Link the entitlement to a product. Any customer with an active or trialing subscription to this product will automatically have the entitlement unlocked.

```bash theme={null}
curl -X POST https://api.fype.dev/v1/entitlements/{entitlement_uuid}/products \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "product_uuid"
  }'
```