You are viewing the documentation for Chargebee API V2. If you're using the older version (V1), click here.

The subscription entitlement object represents the entitlements a subscription has towards a feature. A subscription can have multiple subscription_entitlements, each corresponding to a feature it is entitled to. The subscription_entitlement includes both the effective (or final) entitlement and its components. The components consist of inherited_entitlements and any entitlement_overrides.

Effective and Component Entitlements

The effective entitlement of a given subscription towards a given feature is given by subscription_entitlement.value. It is the final entitlement derived from the entitlement components. There are two types of component entitlements:

  • inherited_entitlements: Inherited entitlements are derived from the item_entitlements of the subscription's items. The following section describes how this works, providing examples for each feature type.
  • entitlement_overrides: An overridden entitlement is that which is granted explicitly on the subscription for a feature. Such an entitlement, when present, becomes the effective entitlement for the subscription, thereby overriding any inherited entitlement towards the feature. An entitlement_override can be temporary such that it expires at some point in time and is no longer returned. See entitlement_overrides.

How inherited_entitlements.value is determined

The inherited_entitlements.value is determined from the item_entitlements of the items in the subscription and based on feature.type:

In this case,
  • if any of the subscription_item_entitlements[].values is unlimited, then inherited_entitlements.value is also unlimited.
  • otherwise, the inherited_entitlements.value is the sum of all the subscription_item_entitlements[].values.

Example

Consider the following…

  • A feature of type quantity, named User Licenses has entitlement levels defined as:
    • feature.levels[0].value = 5
    • feature.levels[1].value=10
    • feature.levels[2].value=30
  • Also, feature.levels[i].is_unlimited is false for all values of i, which means that the feature has no Unlimited level.
  • A quantity-based plan-item named Standard has entitlements to the above feature defined as item_entitlement.value = 10.
  • A quantity-based addon-item Extra licenses - small has entitlements to the same feature defined as item_entitlement.value = 5.
  • A subscription contains:
    • 2 units of an item price under the plan-item Standard. Which is seen in the subscription as subscription.subscription_items[0].quantity = 2.
    • 3 units of an item price price-1 under the addon-item Extra licenses - small. Which is subscription.subscription_items[1].quantity = 3
    • 4 units of an item price price-2 under the addon-item Extra licenses - small. Which is subscription.subscription_items[2].quantity = 4

We derive inherited_entitlements.value as follows:

  1. Determine subscription_item_entitlements[i].item_entitlement_value for both the items. The value is the same as item_entitlement.value, so we have:
    • subscription_item_entitlements[0].item_entitlement_value = 10 for the plan
    • subscription_item_entitlements[1].item_entitlement_value = 5 for the addon
  2. Determine subscription_item_entitlements[i].subscription_item_quantity for both the items:
    • For the plan-item, the value is the same as the item price quantity (subscription.subscription_items[0].quantity). So we have subscription_item_entitlements[0].subscription_item_quantity= 2.
    • For the addon-item, since two item prices price-1 and price-2 have been added to the subscription, the quantity of the item price that was updated last in Chargebee is considered. If we assume price-1 was updated last, then the quantity of price-1 in the subscription is considered, which is subscription.subscription_items[1].quantity. So we have subscription_item_entitlements[n].subscription_item_quantity= 3
  3. Determine subscription_item_entitlements[].value for the items. The value is given by subscription_item_entitlements[i].item_entitlement_value × subscription_item_entitlements[i].subscription_item_quantity, so we have:
    • subscription_item_entitlements[0].value = 10 × 2 = 20 for the plan.
    • subscription_item_entitlements[1].value = 5 × 3 = 15 for the addon.
  4. Calculate inherited_entitlements.value as the sum of all the subscription_item_entitlements[i].values, so we have: 20 + 15 = 35 as the inherited entitlement of the subscription towards the feature named User Licenses.

In this case,

  • if any of the subscription_item_entitlements[i].values is unlimited, then inherited_entitlements.value is also unlimited.
  • otherwise, the inherited_entitlements.value is the sum of all the subscription_item_entitlements[i].values. Additionally, when the value of levels[i].is_unlimited for the feature is false for values of i, and the sum of all subscription_item_entitlements[i].values exceeds feature.levels[1].value (the upper limit of the range), then inherited_entitlements.value is set to feature.levels[1].value.

Example

Consider the following…

  • A feature of type range, named API Rate Limit has entitlement levels defined as:
    • feature.levels[0].value = 100
    • levels[1].value = 1000
  • Also, feature.levels[i].is_unlimited as false for all values of i, which means that the feature has no Unlimited level.
  • A quantity-based plan-item namedStandard has entitlements to the above feature defined as item_entitlement.value = 400.
  • a quantity-based addon-item API Boost - small has entitlements to the same feature defined as item_entitlement.value = 100.
  • A subscription contains:
    • 2 units of an item price under the plan-item Standard. Which is seen in the subscription as subscription.subscription_items[0].quantity = 2.
    • 3 units of an item price price-1 under the addon-item API Boost - small. Which is subscription.subscription_items[1].quantity = 3.
    • 4 units of an item price price-2 under the addon-item API Boost - small. Which is subscription.subscription_items[1].quantity = 4.

We derive inherited_entitlements.value, as follows:

  1. Determine subscription_item_entitlements[i].item_entitlement_value for both the items. The value is the same as item_entitlement.value, so we have:
    • subscription_item_entitlements[0].item_entitlement_value = 400 for the plan
    • subscription_item_entitlements[0].item_entitlement_value = 100 for the addon
  2. Determine subscription_item_entitlements[i].subscription_item_quantity for both the items:
    • For the plan-item, the value is the same as the item rice quantity (subscription.subscription_items[0].quantity) so we have: subscription_item_entitlements[0].subscription_item_quantity = 2
    • For the addon-item, since two item prices price-1 and price-2 have been added to the subscription, the quantity of the item price that was updated last in Chargebee is considered. If we assume price-1 was updated last, then the quantity of price-1 in the subscription is considered, which is subscription.subscription_items[1].quantity. So we have subscription_item_entitlements[1].subscription_item_quantity = 3
  3. Determine subscription_item_entitlements[i].value for the items. The value is given by subscription_item_entitlements[i].item_entitlement_value × subscription_item_entitlements[i].subscription_item_quantity, so we have:
    • subscription_item_entitlements[0].value = 400 × 2 = 800 for the plan
    • subscription_item_entitlements[1].value = 100 × 3 = 300 for the addon
  4. Calculate the sum of all the subscription_item_entitlements[i].values, so we have: 800 + 300 = 1100
  5. Determine inherited_entitlements.value: Since feature.levels[i].is_unlimited is false for all values of i, and the sum in the previous step exceeds the upper limit of the range (1000) given by levels[1].value, the inherited_entitlements.value is the same as levels[1].value which is 1000. So 1000 is the inherited entitlement of the subscription towards the feature named API Rate Limit.

In this case, the inherited_entitlements.value is the highest of all subscription_item_entitlements[].values

Example

Consider the following…

  • A feature of type custom, named Email Support that has entitlement levels defined as levels[0].value = “email”, levels[1].value = “24×5”, and levels[2].value = ”24×7”.
  • A plan-item named Standard has entitlements to the above feature defined as item_entitlement[i].value = ”24x5”.
  • An addon-item Premium Support has entitlements to the same feature defined as item_entitlement.value[j] = ”24× 7”.
  • A subscription subscribes to the Standard plan with the Premium Support addon.

In this case, inherited_entitlements.value = 24×7, which is the highest of 24x5 and 24×7 as determined by their relative positions in the feature.levels[].value list.

In this case, the inherited_entitlements.value is set to true when any of the subscription_item_entitlements[].values is true.

Sample subscription entitlement [ JSON ]

{ "id": "KyVnHhSBWlm1j2m7", "subscription_id": "JzDnHhSBWlm1j1n4", "feature_id": "salesforce-integration", "feature_name": "Salesforce integration", "value": "available", "name": "", "is_overridden": false }

API Index URL GET

https://{site}.chargebee.com/api/v2/subscription_entitlements
id
string, max chars=150
Unique identifier for the subscription entitlement. This is always auto-generated.
subscription_id
string, max chars=50
The id of the subscription to which this entitlement belongs.
feature_id
optional, string, max chars=50
The id of the feature towards which this subscription entitlement has been granted.
feature_name
optional, string, max chars=50
The name of the feature towards which this subscription entitlement has been granted.
feature_unit
optional, string, max chars=50
The unit of measure for the feature when its type is either quantity or range.
value
optional, string, max chars=50
The value denoting the effective entitlement level that the subscription has towards the feature. When components.entitlement_override is present, then this is the same as components.entitlement_override.value. Otherwise, it is components.inherited_entitlements.value.
name
optional, string, max chars=50
The display name of the effective entitlement level. When components.entitlement_override is present, then this is the same as components.entitlement_override.name. Otherwise, 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 inherited_entitlements.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 inherited_entitlements.value.
  • When feature.type is switch: name is not applicable.

is_overridden
boolean
Indicates that components.entitlement_overrides exists.
is_enabled
boolean
Indicates that components.is_enabled exists.
expires_at
optional, timestamp(UTC) in seconds
Timestamp when the subscription entitlements are going to expire.
components
Show attributes[+]
optional, component
The component entitlements that constitute this subscription_entitlement. The effective entitlement value and name are determined from these component entitlements.
Component attributes
entitlement_overrides [+]
optional, component
The component entitlements that constitute this subscription_entitlement. The effective entitlement value and name are determined from these component entitlements.
Entitlement override attributes
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.
.

Retrieves the list of subscription_entitlements for the subscription.

Note:

The components attribute is not returned for any of the subscription_entitlements. Use the retrieve operation(coming soon) to obtain the components.

Sample Request
curl  https://{site}.chargebee.com/api/v2/subscriptions/JzDnHhSBWlm1j1n4/subscription_entitlements \
     -G  \
     -u {site_api_key}:
copy
curl  https://{site}.chargebee.com/api/v2/subscriptions/JzDnHhSBWlm1j1n4/subscription_entitlements \
     -G  \
     -u {site_api_key}:

Sample Response [ JSON ]

Show more...
{"list": [ {"subscription_entitlement": { "id": "KyVnHhSBWlm1j2m7", "subscription_id": "JzDnHhSBWlm1j1n4", "feature_id": "salesforce-integration", "feature_name": "Salesforce integration", "value": "available", "name": "", "is_overridden": false }}, {..} ]}

URL Format GET

https://{site}.chargebee.com/api/v2/subscriptions/{subscription_id}/subscription_entitlements
limit
optional, integer, default=10, min=1, max=100
The number of resources to be returned.
offset
optional, string, max chars=1000
Determines your position in the list for pagination. To ensure that the next page is retrieved correctly, always set offset to the value of next_offset obtained in the previous iteration of the API call.
always returned
Resource object representing subscription_entitlement
next_offset
optional, string, max chars=1000
This attribute is returned only if more resources are present. To fetch the next set of resources use this value for the input parameter “offset”.
Sample Request
# To enable/disable features for a subscription
curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__In7qXwSnDpTCF1k/subscription_entitlements/set_availability \
     -X POST  \
     -u {site_api_key}:\
     -d is_enabled="false" \
     -d subscription_entitlements[feature_id][0]="fea-e1958ced-c993-4235-bb10-ed67934b4c90"
copy
# To enable/disable features for a subscription
curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__In7qXwSnDpTCF1k/subscription_entitlements/set_availability \
     -X POST  \
     -u {site_api_key}:\
     -d is_enabled="false" \
     -d subscription_entitlements[feature_id][0]="fea-e1958ced-c993-4235-bb10-ed67934b4c90"

Sample Response [ JSON ]

Show more...
{"list": [ {"subscription_entitlement": { "feature_id": "fea-e1958ced-c993-4235-bb10-ed67934b4c90", "feature_name": "Phone Support", "feature_type": "custom", "is_enabled": false, "is_overridden": true, "name": "Disabled", "object": "subscription_entitlement", "subscription_id": "__test__In7qXwSnDpTCF1k" }}, {..} ]}

URL Format POST

https://{site}.chargebee.com/api/v2/subscriptions/{subscription_id}/subscription_entitlements/set_availability
is_enabled
required, boolean
Specifies whether the subscription_entitlements are to be enabled or disabled.
+
subscription_entitlements
Parameters for subscription_entitlements. Multiple subscription_entitlements can be passed by specifying unique indices.
pass parameters as subscription_entitlements[<param name>][<idx:0..n>]
subscription_entitlements[feature_id][0..n]
required, string, max chars=50
The id of the feature towards which the subscription_entitlement is to be enabled or disabled. An error is returned if a subscription_entitlement does not exist for the feature.
always returned
Resource object representing subscription_entitlement