Skip to main content

​
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

EventDescription
entitlement.grantedEntitlement assigned
entitlement.revokedEntitlement removed
entitlement.usage_warningApproaching limit
entitlement.limit_exceededLimit exceeded
entitlement.resetUsage 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.