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:

{
  "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:

{
  "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:

{
  "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:

{
  "key": "advanced_analytics",
  "type": "boolean",
  "value": true
}

Quantity (Usage Limit)

Set numeric limits:

{
  "key": "api_calls",
  "type": "quantity",
  "value": 100000,
  "resetPeriod": "monthly"
}

Tier (Access Level)

Define access levels:

{
  "key": "support_level",
  "type": "tier",
  "value": "premium",
  "allowedValues": ["basic", "standard", "premium", "enterprise"]
}

Unlimited

No restrictions:

{
  "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

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:

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:

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:

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

curl https://api.alguna.io/subscriptions/sub_123/entitlements/api_calls \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

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

All Active Entitlements

curl https://api.alguna.io/subscriptions/sub_123/active-entitlements \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "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:

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

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

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:

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

{
  "key": "api_calls",
  "overageHandling": "block",
  "blockMessage": "API call limit exceeded. Please upgrade."
}

Allow Overages (with billing)

{
  "key": "api_calls",
  "overageHandling": "allow",
  "overagePrice": "0.001",
  "overagePriceUnit": "per_call"
}

Soft Limit (warning only)

{
  "key": "api_calls",
  "overageHandling": "warn",
  "warningThreshold": 80
}

---

Time-Based Entitlements

Trial Period

Grant temporary access:

{
  "configKey": "advanced_analytics",
  "value": true,
  "startDate": "2024-01-01",
  "endDate": "2024-01-14",
  "reason": "14-day trial"
}

Promotional Access

{
  "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

{
  "transitionPolicy": {
    "onUpgrade": {
      "action": "replace",
      "carryOverUsage": false
    }
  }
}

On Downgrade

{
  "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

{
  "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

// 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

Use Templates

Create templates for consistent plan entitlements.

Set Warning Thresholds

Alert customers before they hit limits.

Plan for Overages

Decide upfront how to handle limit exceeds.

Cache Entitlements

Cache entitlement checks for performance.

---

Next Steps

Feature Access

Control feature flags.

Templates

Create entitlement templates.