Entitlements API

The Entitlements API allows you to check whether customers are entitled to specific features in your application. It supports both subscription-based and credit-based entitlements, providing real-time access control for your product features.

Overview

Entitlements determine what features customers can access based on:

• Subscription Plans: Features included in their current plan
• Feature Overrides: Manual overrides for specific customers
• Credit Grants: Time-limited credits that provide access to features
• Usage Limits: Numeric limits for metered features with real-time usage tracking

Entitlement Sources

Entitlements can come from four different sources:

• plan - Features included in the customer's subscription plan
• override - Manual overrides applied to specific customers
• credits - Credit-based entitlements with usage allowances
• default - Default fallback entitlements

Customer ID Types

The API supports two types of customer identification:

• Internal Customer ID: Your system's internal customer identifier
• External Customer ID: External identifiers from your application (set via isExtCustId=true)

Authentication

All API requests require authentication via merchant credentials.

Endpoints

Get All Customer Entitlements

Get all feature entitlements for a specific customer.

GET https://api.getlumen.dev/v1/entitlements/{customerId}?isExtCustId=false

Parameters

Response

{
  "entitlements": [
    {
      "entitled": true,
      "feature": {
        "slug": "api-calls",
        "value": 1000
      },
      "source": "plan",
      "usages": [
        {
          "metricId": "metric_123",
          "usage": 150
        }
      ],
      "creditInfo": {
        "creditAllowance": 0,
        "creditsRemaining": 0,
        "nextExpiryDate": null
      }
    },
    {
      "entitled": true,
      "feature": {
        "slug": "premium-support",
        "value": true
      },
      "source": "credits",
      "creditInfo": {
        "creditAllowance": 1,
        "creditsRemaining": 1,
        "nextExpiryDate": "2024-02-01T00:00:00Z"
      }
    }
  ]
}

Get Seat-Aware Customer Entitlements

Get all feature entitlements for a customer, including all members of their organization if they belong to one (seat-based behavior).

GET https://api.getlumen.dev/v1/entitlements/{customerId}/seat-aware?isExtCustId=false

Parameters

Response

{
  "entitlements": [
    {
      "entitled": true,
      "feature": { "slug": "api-calls", "value": 1000 },
      "source": "plan",
      "customerId": "cust_primary",
      "externalCustomerId": "ext_primary"
    },
    {
      "entitled": true,
      "feature": { "slug": "api-calls", "value": 1000 },
      "source": "plan",
      "customerId": "cust_member_1",
      "externalCustomerId": "ext_member_1"
    }
  ]
}

Check Specific Feature Entitlement

Check whether a customer is entitled to a specific feature.

GET https://api.getlumen.dev/v1/entitlements/{customerId}/feature/{featureSlug}?isExtCustId=false

Parameters

Response

{
  "entitled": true,
  "feature": {
    "slug": "api-calls",
    "value": 1000
  },
  "source": "plan",
  "usages": [
    {
      "metricId": "metric_123",
      "usage": 150
    }
  ],
  "creditInfo": {
    "creditAllowance": 500,
    "creditsRemaining": 350,
    "nextExpiryDate": "2024-02-01T00:00:00Z"
  }
}

Response Fields

Batch Check Feature Entitlements

Check multiple feature entitlements in a single request.

POST https://api.getlumen.dev/v1/entitlements/{customerId}/features?isExtCustId=false

Parameters

Request Body

{
  "featureSlugs": ["api-calls", "premium-support", "advanced-analytics"]
}

Request Fields

Response

{
  "entitlements": [
    {
      "entitled": true,
      "feature": {
        "slug": "api-calls",
        "value": 1000
      },
      "source": "plan",
      "usages": [
        {
          "metricId": "metric_123",
          "usage": 150
        }
      ],
      "creditInfo": {
        "creditAllowance": 0,
        "creditsRemaining": 0,
        "nextExpiryDate": null
      }
    },
    {
      "entitled": false,
      "feature": null,
      "source": null,
      "creditInfo": {
        "creditAllowance": 0,
        "creditsRemaining": 0,
        "nextExpiryDate": null
      }
    }
  ]
}

Examples

Check All Customer Entitlements

curl -X GET '/api/entitlements/cust_123?isExtCustId=false' \
  -H "Content-Type: application/json"

Check All Entitlements Using External Customer ID

curl -X GET '/api/entitlements/ext_user_456?isExtCustId=true' \
  -H "Content-Type: application/json"

Check Specific Feature Entitlement

curl -X GET '/api/entitlements/cust_123/feature/api-calls' \
  -H "Content-Type: application/json"

Batch Check Multiple Features

curl -X POST '/api/entitlements/cust_123/features' \
  -H "Content-Type: application/json" \
  -d '{
    "featureSlugs": ["api-calls", "premium-support", "advanced-analytics"]
  }'

Check Feature with External Customer ID

curl -X GET '/api/entitlements/ext_user_456/feature/api-calls?isExtCustId=true' \
  -H "Content-Type: application/json"

Feature Types

Boolean Features

Boolean features are simple on/off switches that determine access to functionality.

{
  "entitled": true,
  "feature": {
    "slug": "premium-support",
    "value": true
  },
  "source": "plan"
}

Numeric Features

Numeric features have usage limits and provide real-time usage tracking.

{
  "entitled": true,
  "feature": {
    "slug": "api-calls",
    "value": 1000
  },
  "source": "plan",
  "usages": [
    {
      "metricId": "api_calls_metric",
      "usage": 150
    }
  ]
}

Credit-Based Features

Features can be entitled through credit grants with expiration dates.

{
  "entitled": true,
  "feature": {
    "slug": "ai-tokens",
    "value": 50000
  },
  "source": "credits",
  "creditInfo": {
    "creditAllowance": 50000,
    "creditsRemaining": 35000,
    "nextExpiryDate": "2024-02-01T00:00:00Z"
  }
}

Entitlement Logic

Credit-Based Entitlements

When customers have credit grants for a feature:

1. Numeric Features: Credits define the usage allowance

   • entitled = true if usage < credit allowance
   • entitled = false if usage >= credit allowance
   • entitled = null if multiple metrics (let client decide)

2. Boolean Features: Credits provide access regardless of plan

   • entitled = true if credits exist
   • Plan feature value is preserved but source indicates credits

Plan-Based Entitlements

Standard subscription plan entitlements:

• Features defined in the customer's active subscription
• Can be overridden at the customer level
• Support both boolean and numeric limits

Priority Order

Entitlements are resolved in this priority order:

1. Credits - Always take precedence for numeric features
2. Customer Overrides - Manual overrides for specific customers
3. Plan Features - Features included in subscription plan
4. Default - Fallback entitlements

Error Responses

400 Bad Request

{
  "error": "featureSlugs array cannot be empty"
}

500 Internal Server Error

{
  "error": "Failed to fetch entitlements"
}

{
  "error": "Failed to check entitlement"
}

{
  "error": "Failed to check entitlements"
}

Important Notes

Customer ID Resolution

• When isExtCustId=true, the API looks up the internal customer ID using the external identifier
• External customer IDs must be unique within the merchant scope
• If external customer ID is not found, the API will treat it as internal ID for backward compatibility

Usage Tracking

• Usage metrics are calculated in real-time based on your event data
• Usage timeframes are aligned with billing periods when available
• Multiple metrics per feature are supported for complex usage scenarios

Credit Expiration

• Credits have expiration dates tracked in nextExpiryDate
• Expired credits are automatically excluded from entitlement calculations
• Credit balances are calculated as: allowance - current_usage

Performance Considerations

• Single feature checks are optimized for low latency
• Batch checks are more efficient for multiple features
• Usage calculations are cached when possible

Data Consistency

• Entitlements reflect real-time subscription and credit status
• Usage data may have slight delays based on event processing
• Failed metric queries default to zero usage

Integration Best Practices

1. Cache Results: Cache entitlement results for performance
2. Handle Null Values: Check for entitled = null on numeric features with multiple metrics
3. Monitor Usage: Use usage data to provide user feedback
4. Credit Tracking: Monitor credit expiration dates for user notifications
5. Error Handling: Implement fallback behavior for API failures

Merchant Isolation

• All entitlement checks are scoped to the authenticated merchant
• Customers and features from other merchants are not accessible
• Complete data isolation is maintained between merchants