Read Subscription Entitlements with the API

Call the entitlements API to retrieve the access rights, usage limits, and service levels resolved for a subscription, so your application’s access control, feature gating, and customer experience stay aligned with what’s configured in Advanced Billing.

GET /subscriptions/{subscription_id}/entitlements

The response returns each feature’s feature_key (prefixed by kind, e.g. usage.api_calls_per_month), name, type (access_right, usage_limit, or service_right), value, enabled, the source_products it resolves from, and (for usage limits) the reset period. Use the feature_key field as a stable identifier in your access control checks.

Example: a monthly API call limit

This example walks through the full configuration of a usage limit, from feature creation to reading the result via the API.

1. In Catalog > Features, create a feature with the name “API Calls per Month”, the key api_calls_per_month, kind Limit, value type Numeric, the unit “calls”, and a monthly default reset period. Click Save Feature.
2. Open the Plan, click the Entitlements tab, click Add Feature, select “API Calls per Month”, enter 10000, and confirm the monthly reset period. Click Save.
   Expected result: 10,000 calls is now the default entitlement for all of the Plan’s price points.
3. Open the annual price point, click its Entitlements tab, and override the value to grant a higher allowance for the annual tier. Click Save. When prompted, choose whether to update existing subscriptions on that price point or leave them as-is.
4. Create a test subscription and open its Entitlements tab.
   Expected result: the table shows the feature’s name, type, and the resolved value for the subscription’s price point.
5. Call GET /subscriptions/{subscription_id}/entitlements.
   Expected result: the response includes the feature’s feature_key (usage.api_calls_per_month), name, type, value, and reset period. Use the feature_key field in your access control checks.

Related information

See Understand Entitlements to learn the concepts behind features, feature kinds, and default and overridden entitlement values.

See Configure Entitlements to set up features, attach them to Plans and Products, and configure price point entitlement values.

See View and Update Subscription Entitlements to review resolved entitlement values on subscriptions and update existing subscriptions after entitlement changes.

See Troubleshoot Entitlements to resolve missing, outdated, or unexpected entitlement values.