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: levels[0].value = 5, levels[1].value=10, and levels[2].value=30.
The feature has levels[].is_unlimited as false for all levels, 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[i].value = 10.
A quantity-based addon-item Extra licenses - small has entitlements to the same feature defined as item_entitlement[j].value = 5.
A subscription subscribes to:

2 units of an item price under the plan-item Standard. (This means that subscription.subscription_items[k].quantity = 2)
3 units of an item price under the addon-item Extra licenses - small. (In other words subscription.subscription_items[l].quantity = 3)

We now arrive at inherited_entitlements.value, as follows:

Determine subscription_item_entitlements[].item_entitlement_value for both the items. The value is the same as item_entitlement.value, so we have:

subscription_item_entitlements[m].item_entitlement_value = 10 for the plan
subscription_item_entitlements[n].item_entitlement_value = 5 for the addon

Determine subscription_item_entitlements[].subscription_item_quantity for both the items. The value is the same as subscription.subscription_items[].quantity, so we have:

subscription_item_entitlements[m].subscription_item_quantity= 2
subscription_item_entitlements[n].subscription_item_quantity= 3

Determine subscription_item_entitlements[].value for the items. The value is given by subscription_item_entitlements[m].item_entitlement_value × subscription_item_entitlements[m].subscription_item_quantity, so we have:

subscription_item_entitlements[m].value = 10 × 2 = 20 for the plan
subscription_item_entitlements[n].value = 5 × 3 = 15 for the addon

Calculate inherited_entitlements.value as the sum of all the subscription_item_entitlements[].values, so we have: 20 + 15 = 35 as the effective or final 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[].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. Additionally, when the value of levels[].is_unlimited for the feature is false for all levels, and the sum of all subscription_item_entitlements[].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: levels[0].value = 100 and levels[1].value = 1000.
The feature has levels[].is_unlimited as false for all levels, 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[i].value = 400.
a quantity-based addon-item API Boost - small has entitlements to the same feature defined as item_entitlement[j].value = 100.
A subscription subscribes to:

2 units of an item price under the plan-item Standard. (This means that subscription.subscription_items[k].quantity = 2)
3 units of an item price under the addon-item API Boost - small. (In other words subscription.subscription_items[l].quantity = 3)

We now arrive at inherited_entitlements.value, as follows:

Determine subscription_item_entitlements[].item_entitlement_value for both the items. The value is the same as item_entitlement.value, so we have:

subscription_item_entitlements[m].item_entitlement_value = 400 for the plan
subscription_item_entitlements[n].item_entitlement_value = 100 for the addon

Determine subscription_item_entitlements[].subscription_item_quantity for both the items. The value is the same as subscription.subscription_items[].quantity, so we have:

subscription_item_entitlements[m].subscription_item_quantity= 2
subscription_item_entitlements[n].subscription_item_quantity= 3

Determine subscription_item_entitlements[].value for the items. The value is given by subscription_item_entitlements[m].item_entitlement_value × subscription_item_entitlements[m].subscription_item_quantity, so we have:

subscription_item_entitlements[m].value = 400 × 2 = 800 for the plan
subscription_item_entitlements[n].value = 100 × 3 = 300 for the addon

Calculate the sum of all the subscription_item_entitlements[].values, so we have: 800 + 300 = 1100
Determine inherited_entitlements.value: Since levels[].is_unlimited is false for all levels of the feature, and the above sum exceeds the upper limit of the range given by levels[1].value, the inherited_entitlements.value is the same as levels[1].value which is 1000. So 1000 is the effective or final 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

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, subscription_entitlement_override
When a subscription entitlement has been explicitly overridden, this object contains the details of said override. An entitlement_override can be temporary such that it expires at some point in time and is no longer returned.

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.

inherited_entitlements [+]

optional, inherited_entitlement
This object contains entitlements that are derived from individual item entitlements associated with the subscription.

Inherited entitlement attributes

value

optional, string, max chars=50
The value of the inherited entitlement as derived from individual item entitlements.

subscription_item_entitlements [+]

optional, list of subscription_item_entitlement
The subscription can have multiple items. One or more of those items can be entitled to the feature. This object contains relevant details from all those item_entitlements.

Subscription item entitlement attributes

id

string, max chars=150
A unique id for this subscription item entitlement. It is always autogenerated.

item_entitlement_id

optional, string, max chars=50
The unique id of the item entitlement. This is the same as item_entitlement.id.

item_entitlement_value

optional, string, max chars=50
The level of entitlement that the item has towards the feature. This is the same as item_entitlement.value.

item_id

optional, string, max chars=50
The unique id of the item to which this entitlement belongs. This is the same as item_entitlement.item_id.

item_type

optional, string, max chars=50
The type of the item.

subscription_item_quantity

optional, string, max chars=50
The quantity of the item purchased in the same subscription. This is the same as subscription.subscription_items.quantity.

value

optional, string, max chars=50
The value of the entitlement that the subscription has via this item entitlement.

When feature.type is quantity or range: This is calculated as item_entitlement_value × subscription_item_quantity. When subscription_item_quantity is not applicable, the value is item_entitlement_value.
For other feature.types: It is the same as item_entitlement_value.

name

optional, string, max chars=50
A case-sensitive display name for the entitlement level. This is the same as item_entitlement.name.

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

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`