Check Feature Access

Use when checking what a customer can access (e.g. feature gating or usage limits). Supports optional filters (feature_ids, subscription_ids).

GET /v1/customers/{id}/entitlements

cURL - Check all feature access

curl -X GET "https://api.flexprice.io/v1/customers/cust_1234/entitlements" \
  -H "Authorization: Bearer YOUR_API_KEY"

200

{
  "customer_id": "cust_1234",
  "entitlements": [
    {
      "id": "ent_abc123",
      "feature_id": "feat_api_calls",
      "feature_type": "METERED",
      "is_enabled": true,
      "usage_limit": 10000,
      "usage_reset_period": "MONTHLY",
      "is_soft_limit": false,
      "current_usage": 2350,
      "remaining_usage": 7650,
      "feature": {
        "id": "feat_api_calls",
        "name": "API Calls",
        "lookup_key": "api_calls",
        "type": "METERED",
        "unit_singular": "API call",
        "unit_plural": "API calls"
      },
      "entity_type": "PLAN",
      "entity_id": "plan_pro"
    },
    {
      "id": "ent_def456",
      "feature_id": "feat_advanced_analytics",
      "feature_type": "BOOLEAN",
      "is_enabled": true,
      "feature": {
        "id": "feat_advanced_analytics",
        "name": "Advanced Analytics",
        "lookup_key": "advanced_analytics",
        "type": "BOOLEAN"
      },
      "entity_type": "PLAN",
      "entity_id": "plan_pro"
    },
    {
      "id": "ent_ghi789",
      "feature_id": "feat_team_members",
      "feature_type": "STATIC",
      "is_enabled": true,
      "static_value": "10",
      "feature": {
        "id": "feat_team_members",
        "name": "Team Members",
        "lookup_key": "team_members",
        "type": "STATIC"
      },
      "entity_type": "PLAN",
      "entity_id": "plan_pro"
    }
  ],
  "subscriptions": [
    {
      "id": "sub_5678",
      "plan_id": "plan_pro",
      "status": "ACTIVE"
    }
  ]
}

This endpoint returns customer entitlements which determine feature access. Use it to gate features in your application based on the customer’s active subscriptions and plan entitlements.

Path Parameters

id · string · required

The unique identifier of the customer

Query Parameters

feature_ids · array

Filter by specific feature IDs

Can be provided multiple times: ?feature_ids=feat_1&feature_ids=feat_2

subscription_ids · array

Filter by specific subscription IDs

Can be provided multiple times: ?subscription_ids=sub_1&subscription_ids=sub_2

feature_types · array

Filter by feature types

Values: BOOLEAN, METERED, STATIC

Response

customer_id · string

ID of the customer

entitlements · array

Array of entitlement objects representing the customer’s feature access

Show Entitlement object

id · string

Unique identifier for the entitlement

feature_id · string

ID of the feature

feature_type · string

Type of feature (BOOLEAN, METERED, or STATIC)

is_enabled · boolean

Whether the feature is enabled for this customer

usage_limit · integer

Usage limit for metered features (null if unlimited)

usage_reset_period · string

How often usage resets for metered features

Values: NONE, DAILY, WEEKLY, MONTHLY, BILLING_PERIOD

is_soft_limit · boolean

Whether the limit is a soft limit (warning) or hard limit (enforcement)

static_value · string

Value for static features (e.g., “5”, “10GB”, “Unlimited”)

current_usage · integer

Current usage for metered features in the current period

remaining_usage · integer

Remaining usage before hitting the limit (null if unlimited)

feature · object

Feature details (name, description, etc.)

entity_type · string

Type of entity this entitlement comes from

Values: PLAN, ADDON, SUBSCRIPTION

entity_id · string

ID of the entity (plan_id, addon_id, or subscription_id)

subscriptions · array

Array of active subscriptions for the customer

cURL - Check all feature access

curl -X GET "https://api.flexprice.io/v1/customers/cust_1234/entitlements" \
  -H "Authorization: Bearer YOUR_API_KEY"

200

{
  "customer_id": "cust_1234",
  "entitlements": [
    {
      "id": "ent_abc123",
      "feature_id": "feat_api_calls",
      "feature_type": "METERED",
      "is_enabled": true,
      "usage_limit": 10000,
      "usage_reset_period": "MONTHLY",
      "is_soft_limit": false,
      "current_usage": 2350,
      "remaining_usage": 7650,
      "feature": {
        "id": "feat_api_calls",
        "name": "API Calls",
        "lookup_key": "api_calls",
        "type": "METERED",
        "unit_singular": "API call",
        "unit_plural": "API calls"
      },
      "entity_type": "PLAN",
      "entity_id": "plan_pro"
    },
    {
      "id": "ent_def456",
      "feature_id": "feat_advanced_analytics",
      "feature_type": "BOOLEAN",
      "is_enabled": true,
      "feature": {
        "id": "feat_advanced_analytics",
        "name": "Advanced Analytics",
        "lookup_key": "advanced_analytics",
        "type": "BOOLEAN"
      },
      "entity_type": "PLAN",
      "entity_id": "plan_pro"
    },
    {
      "id": "ent_ghi789",
      "feature_id": "feat_team_members",
      "feature_type": "STATIC",
      "is_enabled": true,
      "static_value": "10",
      "feature": {
        "id": "feat_team_members",
        "name": "Team Members",
        "lookup_key": "team_members",
        "type": "STATIC"
      },
      "entity_type": "PLAN",
      "entity_id": "plan_pro"
    }
  ],
  "subscriptions": [
    {
      "id": "sub_5678",
      "plan_id": "plan_pro",
      "status": "ACTIVE"
    }
  ]
}

Feature Gating Patterns

Boolean Feature Gates

For simple on/off features, check the is_enabled flag:

entitlements = client.customers.entitlements.list(
    customer_id,
    feature_ids=["feat_advanced_analytics"]
)

analytics_enabled = (
    len(entitlements.entitlements) > 0 and
    entitlements.entitlements[0].is_enabled
)

if analytics_enabled:
    # Show advanced analytics
    pass
else:
    # Show upgrade prompt
    pass

Metered Feature with Usage Tracking

For usage-based features, check both access and remaining usage:

const entitlements = await client.customers.entitlements.list(
  customerId,
  { featureIds: ["feat_api_calls"] }
);

const apiAccess = entitlements.entitlements[0];

if (!apiAccess?.isEnabled) {
  throw new Error("API access not available on your plan");
}

if (apiAccess.remainingUsage !== null && apiAccess.remainingUsage <= 0) {
  if (apiAccess.isSoftLimit) {
    // Warn but allow
    console.warn("You've exceeded your API limit");
  } else {
    // Hard limit - block
    throw new Error("API limit exceeded. Please upgrade your plan.");
  }
}

// Allow API call and track usage
await makeApiCall();

Static Feature Values

For configuration-based features, use the static_value:

entitlements, _ := client.Customers.Entitlements.List(
    ctx,
    customerID,
    &flexprice.CustomerEntitlementsParams{
        FeatureIDs: []string{"feat_team_members"},
    },
)

teamAccess := entitlements.Entitlements[0]
maxTeamMembers, _ := strconv.Atoi(teamAccess.StaticValue)

if currentTeamSize >= maxTeamMembers {
    return errors.New("Team member limit reached. Please upgrade.")
}

Caching Recommendations

To reduce latency, cache entitlement responses for a few minutes. Invalidate the cache when:

• Customer’s subscription changes
• Plan is modified
• Entitlements are manually updated

import redis
import json
from datetime import timedelta

redis_client = redis.Redis()

def check_feature_access(customer_id: str, feature_id: str) -> dict:
    cache_key = f"entitlements:{customer_id}"
    
    # Try cache first
    cached = redis_client.get(cache_key)
    if cached:
        entitlements = json.loads(cached)
    else:
        # Fetch from API
        response = client.customers.entitlements.list(customer_id)
        entitlements = response.entitlements
        
        # Cache for 5 minutes
        redis_client.setex(
            cache_key,
            timedelta(minutes=5),
            json.dumps(entitlements)
        )
    
    # Find specific feature
    return next(
        (e for e in entitlements if e.feature_id == feature_id),
        None
    )

Webhook Integration

Stay synchronized with subscription changes by listening to webhooks:

• subscription.activated - Refresh entitlements cache
• subscription.canceled - Clear entitlements cache
• subscription.updated - Refresh if plan changed
• entitlement.updated - Refresh entitlements cache