Subscription entitlements

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:

When the `feature.type` is `quantity`

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:

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

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

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.

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.

When the `feature.type` is `range`

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:

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

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

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

Calculate the sum of all the subscription_item_entitlements[i].values, so we have: 800 + 300 = 1100
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.

When the `feature.type` is `custom`

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.

When the `feature.type` is `switch`

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 ]

{
    "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

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 ]

{"list": [
    {"subscription_entitlement": {
        "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.

subscription_entitlement

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”.

Enables or disables specific subscription_entitlements for a subscription.

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 ]

{"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.

subscription_entitlement

always returned
Resource object representing subscription_entitlement

Effective and Component Entitlements

How `inherited_entitlements.value` is determined

When the `feature.type` is `quantity`

Example

When the `feature.type` is `range`

Example

When the `feature.type` is `custom`

Example

When the `feature.type` is `switch`

Sample subscription entitlement [ JSON ]

API Index URL GET

Subscription entitlement attributes

List subscription entitlements¶

Sample Response [ JSON ]

URL Format GET

Input Parameters

Returns

Enable/disable subscription entitlements¶

Sample Response [ JSON ]

URL Format POST

Input Parameters

Returns

Subscription entitlements

Effective and Component Entitlements

How inherited_entitlements.value is determined

When the feature.type is quantity

Example

When the feature.type is range

Example

When the feature.type is custom

Example

When the feature.type is switch

Sample subscription entitlement [ JSON ]

API Index URL GET

Subscription entitlement attributes

List subscription entitlements¶

Sample Response [ JSON ]

URL Format GET

Input Parameters

Returns

Enable/disable subscription entitlements¶

Sample Response [ JSON ]

URL Format POST

Input Parameters

Returns

How `inherited_entitlements.value` is determined

When the `feature.type` is `quantity`

When the `feature.type` is `range`

When the `feature.type` is `custom`

When the `feature.type` is `switch`