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 ]

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

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

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

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`