Lumen Documentation

What are Entitlements?

Entitlements determine what features customers can access based on their subscription, credits, and overrides. This is Lumen's core innovation — instead of hardcoding plan checks in your code, you check feature entitlements. This lets you change pricing and packaging from the Lumen dashboard without shipping new code.

When to use this

Gate capabilities in your app with feature checks (not plan names).
Enforce limits for usage-based features and show remaining allowance.
Honor credits and per-customer overrides without branching logic.
Surface availability and upgrade prompts in the UI.

How Entitlements are Calculated

Entitlements are calculated in real-time based on multiple sources, resolved in this priority order:

Credits (Highest Priority) - Provide a specific allowance for a feature, overriding any plan limits.
Customer Overrides - Bespoke changes for a specific customer, useful for enterprise deals.
Plan Features - The default features included in the customer's subscription.
Default Fallback - The final value if no other source provides one (usually false).

The Entitlement Flow: Check, Act, Report

For any usage-based feature, the complete developer workflow involves three steps:

Check Entitlement: Before performing an action, ask the Lumen API if the customer is entitled to the feature.
Perform Action: If the check passes, execute your business logic (e.g., process the API call, transcode the video).
Report Usage: After the action succeeds, send a usage event to Lumen. This is the crucial step that decrements the customer's credit balance.

This loop ensures that usage is accurately metered and customers cannot exceed their limits.

Checking Entitlements: A Backend Guide

For any feature gate in your backend, you'll use the Entitlements API.

Boolean Features (On/Off)

For simple yes/no access, check if the entitled flag is true.

# GET /v1/entitlements/{customerId}/feature/premium-support
curl "https://api.getlumen.dev/v1/entitlements/cust_123/feature/premium-support" \
  -H "Authorization: Bearer $LUMEN_API_KEY"

In your backend code, you would check the entitled property of the JSON response:

// Pseudocode for your server, using a generic HTTP client.
async function canAccessPremiumSupport(customerId) {
  const response = await httpClient.get(
    `https://api.getlumen.dev/v1/entitlements/${customerId}/feature/premium-support`
  );
  const data = await response.json();
  return data.entitled;
}

Numeric Features (Usage-Based)

For features with a usage limit, your backend needs to perform the full "Check, Act, Report" flow.

1. Check Entitlement

# GET /v1/entitlements/{customerId}/feature/api-calls
curl "https://api.getlumen.dev/v1/entitlements/cust_123/feature/api-calls" \
  -H "Authorization: Bearer $LUMEN_API_KEY"

The response contains the customer's current usage and remaining credits.

{
  "entitled": true,
  "feature": { "slug": "api-calls", "value": 10000 },
  "source": "credits",
  "creditInfo": {
    "creditAllowance": 10000,
    "creditsRemaining": 8500
  }
}

2. Act & 3. Report

In your code, you would check creditsRemaining, and if it's greater than zero, perform the action and then send the usage event.

// Pseudocode for a serverless function handling an API call.
async function handleApiRequest(request) {
  const customerId = getCustomerId(request);

  // 1. Check
  const entitlement = await checkEntitlement('api-calls', customerId);

  if (!entitlement.entitled || entitlement.creditInfo.creditsRemaining <= 0) {
    return new Response("Limit exceeded", { status: 429 });
  }

  // 2. Act
  const result = await performBusinessLogic();

  // 3. Report
  await reportUsage('api-calls', customerId, { eventValue: 1 });

  return Response.json(result);
}

How Credits Affect Entitlements

Credits are powerful, and they behave slightly differently depending on the feature type.

Key Distinction: How Credits Work

For Numeric Features, a credit grant's allowance becomes the new limit. The source of the entitlement will be reported as credits.
For Boolean Features, a credit grant simply ensures the feature is turned on (entitled: true). It acts like a temporary override, but the source will still be reported as plan or override, not credits.

// Example React component pattern
function FeatureGate({ feature, children, fallback }) {
  const { entitlements, loading } = useAppContext(); // Your app's context
  if (loading) return <Spinner />;

  const isEntitled = entitlements[feature]?.entitled;
  return isEntitled ? children : fallback;
}

// Example Usage
<FeatureGate feature="advanced-analytics" fallback={<UpgradePrompt />}>
  <AdvancedAnalyticsDashboard />
</FeatureGate>

Usage Meters

For numeric features, a simple component can show customers their consumption against their limit.

// Example React component pattern
function UsageMeter({ feature }) {
  const { entitlements } = useAppContext(); // Your app's context
  const entitlement = entitlements[feature];

  if (!entitlement?.entitled) return null;

  const usage = entitlement.usages[0]?.usage ?? 0;
  const limit = entitlement.creditInfo.creditAllowance;
  const percentage = limit > 0 ? (usage / limit) * 100 : 0;

  return (
    <div>
      <span>{usage.toLocaleString()} / {limit.toLocaleString()}</span>
      <div className="progress-bar">
        <div style={{ width: `${percentage}%` }} />
      </div>
    </div>
  );
}

UI vs API

UI: Define plan features and numeric limits through the dashboard
API: Per-subscription/customer overrides, high-volume patterns, and programmatic entitlement management

Common pitfalls

Checking plan names in code instead of feature slugs.
Forgetting to send usage events, which means credit balances will never decrease.
Checking entitlements only on the frontend, which is insecure. Always perform critical checks on the backend.
Caching entitlements too long without a mechanism to invalidate the cache on upgrade.
Ignoring credit precedence over plan limits.

Entitlements