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

# Entitlements Overview

> Manage feature access and subscription entitlements

# Entitlements

Entitlements define what features, resources, or capabilities customers have access to based on their subscription. Use entitlements to control feature access, usage limits, and permission levels across your application.

***

## What Are Entitlements?

Entitlements are access rights granted to customers through their subscription:

* **Feature flags** - Enable/disable features
* **Usage limits** - Set quotas (API calls, storage, users)
* **Permission levels** - Define access tiers
* **Time-based access** - Temporary or trial features

***

## Key Concepts

### Entitlement Configuration

Defines an entitlement type available in your system:

```json theme={null}
{
  "id": "ec_api_calls",
  "key": "api_calls",
  "type": "quantity",
  "displayName": "API Calls per Month",
  "unit": "calls"
}
```

### Entitlement Grant

A specific entitlement assigned to a subscription:

```json theme={null}
{
  "configId": "ec_api_calls",
  "subscriptionId": "sub_123",
  "value": 100000,
  "startDate": "2024-01-01",
  "endDate": "2024-12-31"
}
```

### Entitlement Template

Predefined sets of entitlements for plans:

```json theme={null}
{
  "name": "Enterprise Template",
  "entitlements": [
    {"configId": "ec_api_calls", "value": 1000000},
    {"configId": "ec_users", "value": "unlimited"},
    {"configId": "ec_support", "value": "priority"}
  ]
}
```

***

## Entitlement Types

### Boolean (Feature Flag)

Enable or disable a feature:

```json theme={null}
{
  "key": "advanced_analytics",
  "type": "boolean",
  "value": true
}
```

### Quantity (Usage Limit)

Set numeric limits:

```json theme={null}
{
  "key": "api_calls",
  "type": "quantity",
  "value": 100000,
  "resetPeriod": "monthly"
}
```

### Tier (Access Level)

Define access levels:

```json theme={null}
{
  "key": "support_level",
  "type": "tier",
  "value": "premium",
  "allowedValues": ["basic", "standard", "premium", "enterprise"]
}
```

### Unlimited

No restrictions:

```json theme={null}
{
  "key": "storage",
  "type": "quantity",
  "value": "unlimited"
}
```

***

## Creating Entitlement Configurations

### From the Dashboard

1. Navigate to **Settings > Entitlements**
2. Click **Create Configuration**
3. Fill in:
   * Key (unique identifier)
   * Display name
   * Type (boolean, quantity, tier)
   * Default value
4. Click **Save**

### Via API

```bash theme={null}
curl -X POST https://api.alguna.io/entitlement-configs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "key": "api_calls",
    "displayName": "API Calls",
    "type": "quantity",
    "description": "Monthly API call limit",
    "unit": "calls",
    "defaultValue": 1000,
    "resetPeriod": "monthly"
  }'
```

***

## Granting Entitlements

### On Subscription

Add entitlements when creating a subscription:

```bash theme={null}
curl -X POST https://api.alguna.io/subscriptions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "accountId": "acc_123",
    "planId": "plan_enterprise",
    "entitlements": [
      {"configKey": "api_calls", "value": 500000},
      {"configKey": "advanced_analytics", "value": true},
      {"configKey": "users", "value": 50}
    ]
  }'
```

### From Template

Apply a predefined template:

```bash theme={null}
curl -X POST https://api.alguna.io/subscriptions/sub_123/entitlements-from-template \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "templateId": "tmpl_enterprise"
  }'
```

### Individual Grant

Add a single entitlement:

```bash theme={null}
curl -X POST https://api.alguna.io/subscriptions/sub_123/entitlements \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "configKey": "priority_support",
    "value": true,
    "startDate": "2024-01-01",
    "endDate": "2024-06-30"
  }'
```

***

## Checking Entitlements

### Single Entitlement

```bash theme={null}
curl https://api.alguna.io/subscriptions/sub_123/entitlements/api_calls \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Response:**

```json theme={null}
{
  "key": "api_calls",
  "type": "quantity",
  "value": 500000,
  "used": 125000,
  "remaining": 375000,
  "resetDate": "2024-02-01T00:00:00Z"
}
```

### All Active Entitlements

```bash theme={null}
curl https://api.alguna.io/subscriptions/sub_123/active-entitlements \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Response:**

```json theme={null}
{
  "entitlements": [
    {
      "key": "api_calls",
      "value": 500000,
      "used": 125000,
      "remaining": 375000
    },
    {
      "key": "advanced_analytics",
      "value": true
    },
    {
      "key": "users",
      "value": 50,
      "used": 23,
      "remaining": 27
    }
  ]
}
```

***

## Usage Tracking

### Report Usage

Track consumption against entitlements:

```bash theme={null}
curl -X POST https://api.alguna.io/entitlements/usage \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "subscriptionId": "sub_123",
    "entitlementKey": "api_calls",
    "quantity": 150,
    "timestamp": "2024-01-20T10:00:00Z"
  }'
```

### Get Usage Summary

```bash theme={null}
curl https://api.alguna.io/subscriptions/sub_123/entitlements/api_calls/usage \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "period": "current"
  }'
```

***

## Entitlement Templates

### Creating Templates

```bash theme={null}
curl -X POST https://api.alguna.io/entitlement-templates \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "name": "Starter Plan",
    "description": "Default entitlements for starter plan",
    "entitlements": [
      {"configKey": "api_calls", "value": 10000},
      {"configKey": "users", "value": 5},
      {"configKey": "storage_gb", "value": 10},
      {"configKey": "advanced_analytics", "value": false},
      {"configKey": "support_level", "value": "basic"}
    ]
  }'
```

### Linking to Plans

Associate templates with plans:

```bash theme={null}
curl -X PATCH https://api.alguna.io/plans/plan_starter \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "entitlementTemplateId": "tmpl_starter"
  }'
```

***

## Overages

When usage exceeds entitlement limits:

### Block Access

```json theme={null}
{
  "key": "api_calls",
  "overageHandling": "block",
  "blockMessage": "API call limit exceeded. Please upgrade."
}
```

### Allow Overages (with billing)

```json theme={null}
{
  "key": "api_calls",
  "overageHandling": "allow",
  "overagePrice": "0.001",
  "overagePriceUnit": "per_call"
}
```

### Soft Limit (warning only)

```json theme={null}
{
  "key": "api_calls",
  "overageHandling": "warn",
  "warningThreshold": 80
}
```

***

## Time-Based Entitlements

### Trial Period

Grant temporary access:

```json theme={null}
{
  "configKey": "advanced_analytics",
  "value": true,
  "startDate": "2024-01-01",
  "endDate": "2024-01-14",
  "reason": "14-day trial"
}
```

### Promotional Access

```json theme={null}
{
  "configKey": "priority_support",
  "value": true,
  "startDate": "2024-01-01",
  "endDate": "2024-03-31",
  "reason": "Q1 promotion"
}
```

***

## Transition Policies

Define what happens when subscriptions change:

### On Upgrade

```json theme={null}
{
  "transitionPolicy": {
    "onUpgrade": {
      "action": "replace",
      "carryOverUsage": false
    }
  }
}
```

### On Downgrade

```json theme={null}
{
  "transitionPolicy": {
    "onDowngrade": {
      "action": "prorate",
      "effectiveDate": "end_of_period"
    }
  }
}
```

***

## Webhooks

| Event                        | Description          |
| ---------------------------- | -------------------- |
| `entitlement.granted`        | Entitlement assigned |
| `entitlement.revoked`        | Entitlement removed  |
| `entitlement.usage_warning`  | Approaching limit    |
| `entitlement.limit_exceeded` | Limit exceeded       |
| `entitlement.reset`          | Usage counter reset  |

### Example Webhook

```json theme={null}
{
  "type": "entitlement.usage_warning",
  "timestamp": "2024-01-20T10:00:00Z",
  "data": {
    "subscriptionId": "sub_123",
    "entitlementKey": "api_calls",
    "limit": 100000,
    "used": 80000,
    "percentUsed": 80
  }
}
```

***

## Integration with Your App

### Check Access in Your Code

```javascript theme={null}
// Example: Check if customer has feature access
async function hasFeature(subscriptionId, featureKey) {
  const response = await fetch(
    `https://api.alguna.io/subscriptions/${subscriptionId}/entitlements/${featureKey}`,
    { headers: { 'Authorization': `Bearer ${apiKey}` } }
  );
  const entitlement = await response.json();
  return entitlement.value === true;
}

// Example: Check remaining quota
async function getRemainingQuota(subscriptionId, entitlementKey) {
  const response = await fetch(
    `https://api.alguna.io/subscriptions/${subscriptionId}/entitlements/${entitlementKey}`,
    { headers: { 'Authorization': `Bearer ${apiKey}` } }
  );
  const entitlement = await response.json();
  return entitlement.remaining;
}
```

***

## Best Practices

<CardGroup cols={2}>
  <Card title="Use Templates" icon="copy">
    Create templates for consistent plan entitlements.
  </Card>

  <Card title="Set Warning Thresholds" icon="bell">
    Alert customers before they hit limits.
  </Card>

  <Card title="Plan for Overages" icon="chart-line">
    Decide upfront how to handle limit exceeds.
  </Card>

  <Card title="Cache Entitlements" icon="database">
    Cache entitlement checks for performance.
  </Card>
</CardGroup>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Feature Access" icon="toggle-on" href="/entitlements/feature-access">
    Control feature flags.
  </Card>

  <Card title="Templates" icon="layer-group" href="/entitlements/templates">
    Create entitlement templates.
  </Card>
</CardGroup>