# Subscription entitlements

> For the complete machine-readable documentation index, see [llms.txt](https://apidocs.chargebee.com/llms.txt).


## Overview[](#overview)

The subscription entitlement object represents the entitlement a [subscription](/docs/api/subscriptions) holds for a [feature](/docs/api/features). A subscription can have several subscription entitlements, each tied to a specific feature.

## How subscription entitlements are determined[](#how-subscription-entitlements-are-determined)

### With subscription-level entitlement override[](#with-subscription-level-entitlement-override)

When an [entitlement override](/docs/api/entitlement_overrides) with `entity_type` set to `subscription` is set for a subscription related to a feature, the subscription entitlement takes on the [value](/docs/api/entitlement_overrides/entitlement_override-object#value) of that override.

### Without entitlement overrides[](#without-entitlement-overrides)

If there is no entitlement override for the subscription and feature, the subscription entitlement is based on the [entitlements](/docs/api/entitlements) linked to the [item prices](/docs/api/item_prices) within the [subscription items](/docs/api/subscriptions/subscription-object#subscription_items). If an item price lacks an entitlement record for a particular feature, we consider the entitlement (when available) of its parent [item](/docs/api/items).

The method used to derive the subscription entitlement from these entitlements follows specific rules determined by the feature [type](/docs/api/features/feature-object#type). We outline and provide examples of these rules in the sections below:

Switch feature

#### Summary[](#summary)

Consider a feature of type `switch`. Consider also a subscription whose subscription items correspond to item prices (or items) that have entitlements to the feature. Looking at these entitlements, we first determine the entitlement value held by each subscription item for this feature.

If the entitlement value for the feature held by **any** of the subscription items is `true`, then the subscription entitlement value is also set to `true`. Otherwise, the subscription entitlement value is set to `false`.

#### Example[](#example)

##### 1\. Feature record[](#1-feature-record)

Consider the following [feature](/docs/api/features) record:

Table 1: Feature records.

`id`

`type`

`description`

`xero-integration`

`switch`

An integration with the Xero accounting software.

##### 2\. Entitlement records[](#2-entitlement-records)

Consider the following [entitlement](/docs/api/entitlements) records for the `xero-integration` feature:

Table 2: Entitlement records for the `xero-integration` feature.

`entity_id`

`entity_type`

`value`

`starter`

`plan`

`true`

`starter-monthly-usd`

`plan_price`

`false`

`plus`

`addon`

`true`

##### 3\. Subscription-items records[](#3-subscription-items-records)

Consider that a [subscription](/docs/api/subscriptions) with ID `AzZjAiTl1btqS2lEj` has the following `subscription_items[]` records:

Table 3: Subscription-items records.

Index

`item_price_id`

`quantity`

`0`

`starter-monthly-usd`

`1`

`1`

`plus-monthly-usd`

`1`

`2`

`installation-usd`

`2`

##### 4\. Subscription-item entitlements[](#4-subscription-item-entitlements)

Chargebee Billing now determines the entitlement held by each subscription item based on the entitlements defined in Table 2. This is shown in Table 4. For clarity, we've omitted the `quantity` column because it doesn't affect features with type `switch`.

Table 4: Entitlement values for subscription-items.

Index

`item_price_id`

Entitlement value (determined from Table 2)

`0`

`starter-monthly-usd`

`false` (Matches the value of the plan price.)

`1`

`plus-monthly-usd`

`true` (Inherited from the addon `plus`, as no entitlement is defined for this addon price.)

`2`

`installation-usd`

None (No entitlement defined for the charge item.)

##### 5\. Determining final subscription entitlements[](#5-determining-final-subscription-entitlements)

###### Case 1: Absence of a subscription-level override[](#case-1-absence-of-a-subscription-level-override)

In this scenario, the **final entitlement** (`subscription_entitlement.value`) for the `xero-integration` feature is set to `true` because at least one subscription-item entitlement value is `true`.

###### Case 2: With subscription-level override[](#case-2-with-subscription-level-override)

Suppose there's an [entitlement override](/docs/api/entitlement_overrides) added to the subscription for the feature, as shown below:

Table 5: Entitlement override record for the subscription and feature.

`entity_id`

`entity_type`

`feature_id`

`value`

`AzZjAiTl1btqS2lEj`

`subscription`

`xero-integration`

`false`

Given this override, the subscription's final entitlement value for the `xero-integration` feature is set to `false`.

Quantity feature

#### Summary[](#summary)

Consider a feature of type `quantity`. Consider also a subscription whose subscription items correspond to item prices (or items) that have entitlements to the feature. Looking at these entitlements, we first determine the entitlement value held by each subscription item for this feature.

If the entitlement value for the feature held by any of the subscription items is `unlimited`, then the subscription entitlement value is also `unlimited`. Otherwise, the subscription entitlement value is the sum of all the entitlement values of the subscription items.

#### Example[](#example)

##### 1\. Feature record[](#1-feature-record)

Consider the following feature record:

Table 6: Feature records.

`id`

`type`

`description`

`user_licenses`

`quantity`

The number of user licenses provided.

Suppose that the feature has `feature.levels[]` records as follows:

Table 7: Feature levels records.

`level`

`value`

`is_unlimited`

`0`

`5`

`false`

`1`

`10`

`false`

`2`

`20`

`false`

`3`

Not set.

`true`

##### 2\. Entitlement records[](#2-entitlement-records)

Consider the following entitlement records for the `user_licenses` feature:

Table 8: Entitlement records for the `user_licenses` feature.

`entity_id`

`entity_type`

`value`

`starter`

`plan`

`10`

`starter-monthly-usd`

`plan_price`

`unlimited`

`plus`

`addon`

`5`

`one-time`

`charge`

`5`

##### 3\. Subscription-items records[](#3-subscription-items-records)

Consider that a subscription with ID `AzZjAiTl1btqS2lEj` has the following `subscription_items[]` records:

Table 9: Subscription-items records.

Index

`item_price_id`

`quantity`

`0`

`starter-monthly-usd`

`5`

`1`

`plus-monthly-usd`

`10`

`2`

`one-time-usd`

`1`

##### 4\. Subscription-item entitlements[](#4-subscription-item-entitlements)

Chargebee Billing now determines the entitlement held by each subscription item based on the entitlements defined in Table 8. This is shown in Table 10.

Table 10: Entitlement values for subscription-items.

Index

`item_price_id`

`quantity`

Entitlement value (determined from Table 8)

Entitlement value subtotal (Entitlement value × `quantity`)

`0`

`starter-monthly-usd`

`5`

`unlimited` (Matches the value of the plan price.)

`unlimited` (unlimited x 5)

`1`

`plus-monthly-usd`

`10`

`5` (Inherited from the addon `plus`, as no entitlement is defined for this addon price.)

`50` (5 x 10)

`2`

`one-time-usd`

`1`

`5` (Inherited from the charge `one-time`.)

`5` (5 x 1)

##### 5\. Determining final subscription entitlements[](#5-determining-final-subscription-entitlements)

###### Case 1: Absence of a subscription-level override[](#case-1-absence-of-a-subscription-level-override)

In this scenario, the **final entitlement value** (`subscription_entitlement.value`) for the `user_licenses` feature is the total entitlement value from the last column in Table 10, which amounts to (unlimited + 50 + 5) = `unlimited`.

###### Case 2: With subscription-level override[](#case-2-with-subscription-level-override)

Suppose there's an entitlement override added to the subscription for the feature, as shown below:

Table 11: Entitlement override record for the subscription and feature.

`entity_id`

`entity_type`

`feature_id`

`value`

`AzZjAiTl1btqS2lEj`

`subscription`

`user_licenses`

`20`

Given this override, the subscription's **final entitlement value** for the `user_licenses` feature is set to `20`.

Range feature

#### Summary[](#summary)

Consider a feature of type `range`. Consider also a subscription whose subscription items correspond to item prices (or items) that have entitlements to the feature. Looking at these entitlements, we first determine the entitlement value held by each subscription item for this feature.

If the entitlement value for the feature held by any of the subscription items is `unlimited`, then the subscription entitlement value is also `unlimited`. Otherwise, one of two scenarios are possible:

-   If `feature.levels[1].is_unlimited` is `true`, the subscription entitlement value equals the sum of all entitlement values of the subscription items.
    
-   If `feature.levels[1].is_unlimited` is `false`, the subscription entitlement value equals the sum of all entitlement values of the subscription items without exceeding the maximum value of `feature.level[1].value`.
    

#### Example[](#example)

##### 1\. Feature record[](#1-feature-record)

Consider the following feature record:

Table 12: Feature records.

`id`

`type`

`description`

`api_rate_limit`

`range`

The maximum number of API requests allowed per minute.

Suppose that the feature has `feature.levels[]` records as follows:

Table 13: Feature levels records.

`level`

`value`

`is_unlimited`

`0`

`100`

`false`

`1`

`1000`

`false`

##### 2\. Entitlement records[](#2-entitlement-records)

Consider the following entitlement records for the `api_rate_limit` feature:

Table 14: Entitlement records for the `api_rate_limit` feature.

`entity_id`

`entity_type`

`value`

`premium`

`plan`

`450`

`premium-monthly-usd`

`plan_price`

`400`

`plus`

`addon`

`150`

##### 3\. Subscription-items records[](#3-subscription-items-records)

Consider that a subscription with ID `AzZjAiTl1btqS2lEj` has the following `subscription_items[]` records:

Table 15: Subscription-items records.

Index

`item_price_id`

`quantity`

`0`

`premium-monthly-usd`

`2`

`1`

`plus-monthly-usd`

`2`

##### 4\. Subscription-item entitlements[](#4-subscription-item-entitlements)

Chargebee Billing now determines the entitlement held by each subscription item based on the entitlements defined in Table 14. This is shown in Table 16.

Table 16: Entitlement values for subscription-items.

`subscription_items[]` index

`item_price_id`

`quantity`

Entitlement value (determined from Table 14)

Entitlement value subtotal (Entitlement value x `quantity`)

`0`

`premium-monthly-usd`

`2`

`400` (Matches the value of the plan price.)

`800` (400 x 2)

`1`

`plus-monthly-usd`

`2`

`150` (Inherited from the addon `plus`, as no entitlement is defined for this addon price.)

`300` (150 x 2)

##### 5\. Determining final subscription entitlements[](#5-determining-final-subscription-entitlements)

###### Case 1: `feature.levels[1].is_unlimited` is `false`[](#case-1-featurelevels1isunlimited-is-false)

In this scenario, the **final entitlement value** (`subscription_entitlement.value`) for the `api_rate_limit` feature is the total entitlement value from the last column in Table 16, capped at `feature.levels[1].value`. The total entitlement value is 800 + 300 = 1100. However, `feature.levels[1].value` is `1000`, which is less than 1100. Therefore, the final entitlement is `1000`.

###### Case 2: `feature.levels[1].is_unlimited` is `true`[](#case-2-featurelevels1isunlimited-is-true)

In this scenario, `feature.levels[1].value` is disregarded, and the **final entitlement value** is not capped. In other words, the final entitlement value is `1100`.

Custom feature

#### Summary[](#summary)

Consider a feature of type `custom`. Consider also a subscription whose subscription items correspond to item prices (or items) that have entitlements to the feature.

Looking at these entitlements, we first determine the entitlement value held by each subscription item for this feature. The subscription entitlement value is then set to the highest of these identified values.

#### Example[](#example)

##### 1\. Feature record[](#1-feature-record)

Consider the following feature record:

Table 17: Feature records.

`id`

`type`

`description`

`support`

`custom`

`The form of after-sales support provided to the customer.`

Suppose that the feature has `feature.levels[]` records as follows:

Table 18: Feature levels records.

`level`

`value`

`0`

`email`

`1`

`chat`

`2`

`call`

##### 2\. Entitlement records[](#2-entitlement-records)

Consider the following entitlement records for the `support` feature:

Table 19: Entitlement records for the `api_rate_limit` feature.

`entity_id`

`entity_type`

`value`

`starter`

`plan`

`chat`

`starter-monthly-usd`

`plan_price`

`email`

`plus`

`addon`

`call`

##### 3\. Subscription-items records[](#3-subscription-items-records)

Consider that a subscription with ID `AzZjAiTl1btqS2lEj` has the following `subscription_items[]` records:

Table 20: Subscription-items records.

Index

`item_price_id`

`quantity`

`0`

`starter-monthly-usd`

`2`

`1`

`plus-monthly-usd`

`2`

##### 4\. Subscription-item entitlements[](#4-subscription-item-entitlements)

Chargebee Billing now determines the entitlement held by each subscription item based on the entitlements defined in Table 19. This is shown in Table 21. For clarity, we've omitted the `quantity` column because it doesn't affect features with type `custom`.

Table 21: Entitlement values for subscription-items.

Index

`item_price_id`

Subscription-Item Entitlement Value (determined from Table )

`0`

`starter-monthly-usd`

`email` (Matches the value of the plan price.)

`1`

`plus-monthly-usd`

`call` (Inherited from the addon `plus`, as no entitlement is defined for this addon price.)

##### 5\. Determining final subscription entitlements[](#5-determining-final-subscription-entitlements)

###### Case 1: Absence of a subscription-level override[](#case-1-absence-of-a-subscription-level-override)

In this scenario, the **final entitlement** for the `support` feature is the **highest** of all the subscription-item entitlement values, which in this case is `call`.

###### Case 2: With subscription-level override[](#case-2-with-subscription-level-override)

Suppose there's an entitlement override added to the subscription for the feature, as shown below:

Table 22: Entitlement override record for the subscription and feature.

`entity_id`

`entity_type`

`feature_id`

`value`

`expires_at`

`AzZjAiTl1btqS2lEj`

`subscription`

`support`

`chat`

`1695884985` (7 days from now, assuming today is 2023-09-21.)

Given this override, the subscription's **final entitlement value** for the `support` feature will be `chat` until 2023-09-21 and `call` thereafter.

### With other entity-level entitlement overrides[](#with-other-entity-level-entitlement-overrides)

When an [entitlement override](/docs/api/entitlement_overrides) with `entity_type` set to `plan_price`, `addon_price`, or `charge` is set for a subscription, the override affects the entitlement value used for that specific entity when calculating subscription-item entitlements. If an entitlement override exists for a plan price, addon price, or charge entity, its value is used instead of the regular [entitlement](/docs/api/entitlements) value for that entity.

The method used to derive the subscription entitlement from these overridden values follows the same rules determined by the feature [type](/docs/api/features/feature-object#type) as described in the sections above. We outline and provide examples of these rules in the sections below:

Switch feature

#### Summary[](#summary)

When calculating subscription-item entitlements for a feature of type `switch`, if an entitlement override exists for a plan price, addon price, or charge entity, the override's value is used instead of the regular entitlement value for that entity. The final subscription entitlement value is then determined using the same logic as described in the [Switch feature section](#switch): if the entitlement value for the feature held by **any** of the subscription items is `true`, then the subscription entitlement value is also set to `true`. Otherwise, the subscription entitlement value is set to `false`.

#### Example[](#example)

##### 1\. Feature record[](#1-feature-record)

Consider the following [feature](/docs/api/features) record:

Table 23: Feature records.

`id`

`type`

`description`

`xero-integration`

`switch`

`An integration with the Xero accounting software.`

##### 2\. Entitlement records[](#2-entitlement-records)

Consider the following [entitlement](/docs/api/entitlements) records for the `xero-integration` feature:

Table 24: Entitlement records for the `xero-integration` feature.

`entity_id`

`entity_type`

`value`

`starter`

`plan`

`true`

`starter-monthly-usd`

`plan_price`

`false`

`plus`

`addon`

`false`

##### 3\. Subscription-items records[](#3-subscription-items-records)

Consider that a [subscription](/docs/api/subscriptions) with ID `AzZjAiTl1btqS2lEj` has the following `subscription_items[]` records:

Table 25: Subscription-items records.

Index

`item_price_id`

`quantity`

`0`

`starter-monthly-usd`

`1`

`1`

`plus-monthly-usd`

`1`

##### 4\. Entitlement override records[](#4-entitlement-override-records)

Suppose there's an [entitlement override](/docs/api/entitlement_overrides) added to the subscription for the `plus-monthly-usd` addon price, as shown below:

Table 26: Entitlement override record for the addon price and feature.

`entity_id`

`entity_type`

`feature_id`

`value`

`plus-monthly-usd`

`addon_price`

`xero-integration`

`true`

##### 5\. Subscription-item entitlements[](#5-subscription-item-entitlements)

Chargebee Billing now determines the entitlement held by each subscription item based on the entitlements defined in Table 24, but uses the override value from Table 26 for the `plus-monthly-usd` addon price. This is shown in Table 27. For clarity, we've omitted the `quantity` column because it doesn't affect features with type `switch`.

Table 27: Entitlement values for subscription-items.

Index

`item_price_id`

Entitlement value

`0`

`starter-monthly-usd`

`false` (Matches the value of the plan price entitlement.)

`1`

`plus-monthly-usd`

`true` (Uses the override value from Table 26 instead of inheriting `false` from the addon `plus`.)

##### 6\. Determining final subscription entitlements[](#6-determining-final-subscription-entitlements)

In this scenario, the **final entitlement** for the `xero-integration` feature is set to `true` because at least one subscription-item entitlement value is `true` (the overridden value for `plus-monthly-usd`).

Quantity feature

#### Summary[](#summary)

When calculating subscription-item entitlements for a feature of type `quantity`, if an entitlement override exists for a plan price, addon price, or charge entity, the override's value is used instead of the regular entitlement value for that entity. The final subscription entitlement value is then determined using the same logic as described in the [Quantity feature section](#quantity): if the entitlement value for the feature held by any of the subscription items is `unlimited`, then the subscription entitlement value is also `unlimited`. Otherwise, the subscription entitlement value is the sum of all the entitlement values of the subscription items.

#### Example[](#example)

##### 1\. Feature record[](#1-feature-record)

Consider the following feature record:

Table 28: Feature records.

`id`

`type`

`description`

`user_licenses`

`quantity`

The number of user licenses provided.

Suppose that the feature has `feature.levels[]` records as follows:

Table 29: Feature levels records.

`level`

`value`

`is_unlimited`

`0`

`5`

`false`

`1`

`10`

`false`

`2`

`20`

`false`

##### 2\. Entitlement records[](#2-entitlement-records)

Consider the following entitlement records for the `user_licenses` feature:

Table 30: Entitlement records for the `user_licenses` feature.

`entity_id`

`entity_type`

`value`

`starter`

`plan`

`10`

`starter-monthly-usd`

`plan_price`

`5`

`plus`

`addon`

`5`

`one-time`

`charge`

`5`

##### 3\. Subscription-items records[](#3-subscription-items-records)

Consider that a subscription with ID `AzZjAiTl1btqS2lEj` has the following `subscription_items[]` records:

Table 31: Subscription-items records.

Index

`item_price_id`

`quantity`

`0`

`starter-monthly-usd`

`2`

`1`

`plus-monthly-usd`

`3`

`2`

`one-time-usd`

`1`

##### 4\. Entitlement override records[](#4-entitlement-override-records)

Suppose there are [entitlement override](/docs/api/entitlement_overrides) records added to the subscription for the plan price and charge, as shown below:

Table 32: Entitlement override records for the plan price and charge.

`entity_id`

`entity_type`

`feature_id`

`value`

`starter-monthly-usd`

`plan_price`

`user_licenses`

`10`

`one-time`

`charge`

`user_licenses`

`10`

##### 5\. Subscription-item entitlements[](#5-subscription-item-entitlements)

Chargebee Billing now determines the entitlement held by each subscription item based on the entitlements defined in Table 30, but uses the override values from Table 32 for the `starter-monthly-usd` plan price and `one-time` charge. This is shown in Table 33.

Table 33: Entitlement values for subscription-items.

Index

`item_price_id`

`quantity`

Entitlement value

Entitlement value subtotal (Entitlement value × `quantity`)

`0`

`starter-monthly-usd`

`2`

`10` (Uses the override value from Table 32 instead of the plan price entitlement value of `5`.)

`20` (10 x 2)

`1`

`plus-monthly-usd`

`3`

`5` (Inherited from the addon `plus`, as no entitlement is defined for this addon price and no override exists.)

`15` (5 x 3)

`2`

`one-time-usd`

`1`

`10` (Uses the override value from Table 32 instead of the charge entitlement value of `5`.)

`10` (10 x 1)

##### 6\. Determining final subscription entitlements[](#6-determining-final-subscription-entitlements)

In this scenario, the **final entitlement value** for the `user_licenses` feature is the total entitlement value from the last column in Table 33, which amounts to (20 + 15 + 10) = `45`.

Range feature

#### Summary[](#summary)

When calculating subscription-item entitlements for a feature of type `range`, if an entitlement override exists for a plan price, addon price, or charge entity, the override's value is used instead of the regular entitlement value for that entity. The final subscription entitlement value is then determined using the same logic as described in the [Range feature section](#range): if the entitlement value for the feature held by any of the subscription items is `unlimited`, then the subscription entitlement value is also `unlimited`. Otherwise, one of two scenarios are possible:

-   If `feature.levels[1].is_unlimited` is `true`, the subscription entitlement value equals the sum of all entitlement values of the subscription items.
    
-   If `feature.levels[1].is_unlimited` is `false`, the subscription entitlement value equals the sum of all entitlement values of the subscription items without exceeding the maximum value of `feature.level[1].value`.
    

#### Example[](#example)

##### 1\. Feature record[](#1-feature-record)

Consider the following feature record:

Table 34: Feature records.

`id`

`type`

`description`

`api_rate_limit`

`range`

The maximum number of API requests allowed per minute.

Suppose that the feature has `feature.levels[]` records as follows:

Table 35: Feature levels records.

`level`

`value`

`is_unlimited`

`0`

`100`

`false`

`1`

`1000`

`false`

##### 2\. Entitlement records[](#2-entitlement-records)

Consider the following entitlement records for the `api_rate_limit` feature:

Table 36: Entitlement records for the `api_rate_limit` feature.

`entity_id`

`entity_type`

`value`

`premium`

`plan`

`450`

`premium-monthly-usd`

`plan_price`

`400`

`plus`

`addon`

`150`

##### 3\. Subscription-items records[](#3-subscription-items-records)

Consider that a subscription with ID `AzZjAiTl1btqS2lEj` has the following `subscription_items[]` records:

Table 37: Subscription-items records.

Index

`item_price_id`

`quantity`

`0`

`premium-monthly-usd`

`2`

`1`

`plus-monthly-usd`

`2`

##### 4\. Entitlement override records[](#4-entitlement-override-records)

Suppose there's an [entitlement override](/docs/api/entitlement_overrides) added to the subscription for the addon price, as shown below:

Table 38: Entitlement override record for the addon price and feature.

`entity_id`

`entity_type`

`feature_id`

`value`

`plus-monthly-usd`

`addon_price`

`api_rate_limit`

`300`

##### 5\. Subscription-item entitlements[](#5-subscription-item-entitlements)

Chargebee Billing now determines the entitlement held by each subscription item based on the entitlements defined in Table 36, but uses the override value from Table 38 for the `plus-monthly-usd` addon price. This is shown in Table 39.

Table 39: Entitlement values for subscription-items.

Index

`item_price_id`

`quantity`

Entitlement value

Entitlement value subtotal (Entitlement value × `quantity`)

`0`

`premium-monthly-usd`

`2`

`400` (Matches the value of the plan price.)

`800` (400 x 2)

`1`

`plus-monthly-usd`

`2`

`300` (Uses the override value from Table 38 instead of inheriting `150` from the addon `plus`.)

`600` (300 x 2)

##### 6\. Determining final subscription entitlements[](#6-determining-final-subscription-entitlements)

###### Case 1: `feature.levels[1].is_unlimited` is `false`[](#case-1-featurelevels1isunlimited-is-false)

In this scenario, the **final entitlement value** for the `api_rate_limit` feature is the total entitlement value from the last column in Table 39, capped at `feature.levels[1].value`. The total entitlement value is 800 + 600 = 1400. However, `feature.levels[1].value` is `1000`, which is less than 1400. Therefore, the final entitlement is `1000`.

###### Case 2: `feature.levels[1].is_unlimited` is `true`[](#case-2-featurelevels1isunlimited-is-true)

In this scenario, `feature.levels[1].value` is disregarded, and the **final entitlement value** is not capped. In other words, the final entitlement value is `1400`.

Custom feature

#### Summary[](#summary)

When calculating subscription-item entitlements for a feature of type `custom`, if an entitlement override exists for a plan price, addon price, or charge entity, the override's value is used instead of the regular entitlement value for that entity. The final subscription entitlement value is then determined using the same logic as described in the [Custom feature section](#custom): the subscription entitlement value is set to the highest of the identified subscription-item entitlement values.

#### Example[](#example)

##### 1\. Feature record[](#1-feature-record)

Consider the following feature record:

Table 40: Feature records.

`id`

`type`

`description`

`support`

`custom`

The form of after-sales support provided to the customer.

Suppose that the feature has `feature.levels[]` records as follows:

Table 41: Feature levels records.

`level`

`value`

`0`

`email`

`1`

`chat`

`2`

`call`

##### 2\. Entitlement records[](#2-entitlement-records)

Consider the following entitlement records for the `support` feature:

Table 42: Entitlement records for the `support` feature.

`entity_id`

`entity_type`

`value`

`starter`

`plan`

`chat`

`starter-monthly-usd`

`plan_price`

`email`

`plus`

`addon`

`email`

##### 3\. Subscription-items records[](#3-subscription-items-records)

Consider that a subscription with ID `AzZjAiTl1btqS2lEj` has the following `subscription_items[]` records:

Table 43: Subscription-items records.

Index

`item_price_id`

`quantity`

`0`

`starter-monthly-usd`

`2`

`1`

`plus-monthly-usd`

`2`

##### 4\. Entitlement override records[](#4-entitlement-override-records)

Suppose there's an [entitlement override](/docs/api/entitlement_overrides) added to the subscription for the addon price, as shown below:

Table 44: Entitlement override record for the addon price and feature.

`entity_id`

`entity_type`

`feature_id`

`value`

`plus-monthly-usd`

`addon_price`

`support`

`call`

##### 5\. Subscription-item entitlements[](#5-subscription-item-entitlements)

Chargebee Billing now determines the entitlement held by each subscription item based on the entitlements defined in Table 42, but uses the override value from Table 44 for the `plus-monthly-usd` addon price. This is shown in Table 45. For clarity, we've omitted the `quantity` column because it doesn't affect features with type `custom`.

Table 45: Entitlement values for subscription-items.

Index

`item_price_id`

Subscription-Item Entitlement Value

`0`

`starter-monthly-usd`

`email` (Matches the value of the plan price.)

`1`

`plus-monthly-usd`

`call` (Uses the override value from Table 44 instead of inheriting `email` from the addon `plus`.)

##### 6\. Determining final subscription entitlements[](#6-determining-final-subscription-entitlements)

In this scenario, the **final entitlement** for the `support` feature is the **highest** of all the subscription-item entitlement values, which in this case is `call` (the overridden value for `plus-monthly-usd`).

## Sample Subscription entitlement

```json
{
  "subscription_entitlement": {
    "subscription_id": "Azq8g8ULPXqdL6zM",
    "feature_id": "xero-integration",
    "feature_name": "Xero Integration",
    "feature_type": "SWITCH",
    "value": "true",
    "name": "Available",
    "is_overridden": true,
    "is_enabled": true,
    "object": "subscription_entitlement"
  }
}
```

## Subscription entitlements attributes

## Input Parameters

- `subscription_id` (required, string, max chars=50)
  The unique identifier of the [subscription](/docs/api/subscriptions) .

- `feature_id` (optional, string, max chars=50)
  The unique identifier of the [feature](/docs/api/features) .

- `feature_name` (optional, string, max chars=50)
  The [name of the feature](/docs/api/features/feature-object#name) .

- `feature_unit` (optional, string, max chars=50)
  [The unit of measure](/docs/api/features/feature-object#unit) for the feature when its `type` is either `quantity` or `range` .

- `feature_type` (optional, string, max chars=50)
  Specifies the [type of the feature](/docs/api/features/feature-object#type) associated with the granted subscription entitlement.

- `value` (optional, string, max chars=50)
  The value denoting the final entitlement level that the subscription holds for the feature.
  
  **See also:** [How subscription entitlements are determined](/docs/api/subscription_entitlements).

- `name` (optional, string, max chars=50)
  The display name of the final entitlement level that the subscription holds for the feature. It is derived based on the `type` of feature as follows: - When `feature.type` is `range` or `quantity`: the `name` is the space-separated concatenation of `value` and the pluralized form of `feature_unit`. For example, if `value` is `20` and `feature_unit` is `user`, then `name` becomes `20 users`.
  
  -   When `feature.type` is `custom`: the `name` is the same as `value`.
  -   When `feature.type` is `switch`: `name` is set to `Available` when `value` is `true`; it's set to `Not Available` when `value` is `false`.

- `is_overridden` (required, boolean)
  Indicates whether the entitlement held by the subscription for the feature is overridden via an `[entitlement_overrides](/docs/api/entitlement_overrides)` record.

- `is_enabled` (required, boolean)
  Indicates that `components.is_enabled` exists.

- `expires_at` (optional, timestamp(UTC) in seconds)
  Timestamp when the subscription entitlements are going to expire.

- `components` (optional, component)
  The component entitlements that constitute this `subscription_entitlement`. The effective entitlement `[value](/docs/api/subscription_entitlements/subscription_entitlement-object#value)` and `[name](/docs/api/subscription_entitlements/subscription_entitlement-object#name)` are determined from these component entitlements.
  - `entitlement_overrides` (optional, entitlement_override)
    When a subscription entitlement has been explicitly overridden, this object contains the details of said override. An `entitlement_override` can be [temporary](/docs/api/entitlement_overrides/entitlement_override-object#expires_at) such that it expires at some point in time and is no longer returned.
    - `value` (optional, string, max chars=50)
      The level of entitlement that the subscription has towards the feature. The possible values depend on the value of `feature.type` :
      
      -   When `feature.type` is `custom`: The value can be any one of `levels[].value`.
          
      -   When `feature.type` is `switch`: This value is `true`.
          
      -   When `feature.type` is `quantity`:
          
      -   When `levels[].is_unlimited` is not `true`: The value can be any one of `levels[].value`.
          
      -   When `levels[].is_unlimited` is `true`: The value can also be any one of `levels[].value` or it can be `unlimited` (case-insensitive), indicating unlimited entitlement.
          
      -   When `feature.type` is `range`:
          
      -   When `levels[].is_unlimited` is not `true`: The value can be any whole number between `levels[0].value` and `levels[1].value` (inclusive).
          
      -   When `levels[].is_unlimited` is `true`: The value can be any whole number equal to or greater than `levels[0].value` or it can be `unlimited` (case-insensitive), indicating unlimited entitlement.
    - `name` (optional, string, max chars=50)
      A case-sensitive name for the subscription entitlement override. If it was not provided while creating this subscription entitlement override, then it is derived based on the `feature.type` as follows:
      
      -   When `feature.type` is `range` or `quantity`: the `name` is the space-separated concatenation of value and the pluralized form of `feature_unit`. For example, if `value` is `20` and `feature_unit` is `user`, then `name` becomes `20 users`.
      -   When `feature.type` is `custom`: the `name` is the same as `value`.
      -   When `feature.type` is `switch`: `name` is not applicable.