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
.
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
.inherited_entitlements.value
is determinedThe inherited_entitlements.value
is determined from the item_entitlements
of the items in the subscription and based on feature.type
:
feature.type
is quantity
In this case,
subscription_item_entitlements[].values
is unlimited
, then inherited_entitlements.value
is also unlimited
.inherited_entitlements.value
is the sum of all the subscription_item_entitlements[].values
.Consider the following…
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
.levels[].is_unlimited
as false
for all levels, which means that the feature has no Unlimited
level.Standard
has entitlements to the above feature defined as item_entitlement[i].value
= 10
.Extra licenses - small
has entitlements to the same feature defined as item_entitlement[j].value
= 5
.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:
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 plansubscription_item_entitlements[n].item_entitlement_value
= 5
for the addonsubscription_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
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 plansubscription_item_entitlements[n].value
= 5 × 3 = 15
for the addoninherited_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
.feature.type
is range
In this case,
subscription_item_entitlements[].values
is unlimited
, then inherited_entitlements.value
is also unlimited
.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
.Consider the following…
feature
of type
range
, named API Rate Limit
has entitlement levels defined as: levels[0].value
= 100
and levels[1].value
= 1000
.levels[].is_unlimited
as false
for all levels, which means that the feature has no Unlimited
level.Standard
has entitlements to the above feature defined as item_entitlement[i].value
= 400
.API Boost - small
has entitlements to the same feature defined as item_entitlement[j].value
= 100
.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:
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 plansubscription_item_entitlements[n].item_entitlement_value
= 100
for the addonsubscription_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
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 plansubscription_item_entitlements[n].value
= 100 × 3 = 300
for the addonsubscription_item_entitlements[].values
, so we have: 800 + 300 = 1100
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
.feature.type
is custom
In this case, the inherited_entitlements.value
is the highest of all subscription_item_entitlements[].values
Consider the following…
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”
.Standard
has entitlements to the above feature defined as item_entitlement[i].value
= ”24x5”
.Premium Support
has entitlements to the same feature defined as item_entitlement.value[j]
= ”24×7”
.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.
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
.
{
"id": "KyVnHhSBWlm1j2m7",
"subscription_id": "JzDnHhSBWlm1j1n4",
"feature_id": "salesforce-integration",
"feature_name": "Salesforce integration",
"value": "available",
"name": "",
"is_overridden": false
}
id
of the feature towards which this subscription entitlement has been granted.type
is either quantity
or range
.components.entitlement_override
is present, then this is the same as components.entitlement_override.value
. Otherwise, it is components.inherited_entitlements.value
.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:
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
.feature.type
is custom
: the name
is the same as inherited_entitlements.value
.feature.type
is switch
: name
is not applicable.subscription_entitlement
. The effective entitlement value
and name
are determined from these component entitlements.entitlement_override
can be temporary such that it expires at some point in time and is no longer returned.feature.type
:
feature.type
is custom
: The value can be any one of levels[].value
.feature.type
is switch
: This value is true
.feature.type
is quantity
:levels[].is_unlimited
is not true
: The value can be any one of levels[].value
.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.feature.type
is range
:levels[].is_unlimited
is not true
: The value can be any whole number between levels[0].value
and levels[1].value
(inclusive).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.feature.type
as follows:
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
.feature.type
is custom
: the name
is the same as value
.feature.type
is switch
: name
is not applicable.item_entitlements
.item_entitlement.id
.item_entitlement.value
.item_entitlement.item_id
.subscription.subscription_items.quantity
.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
.feature.types
: It is the same as item_entitlement_value
.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
.
curl https://{site}.chargebee.com/api/v2/subscriptions/JzDnHhSBWlm1j1n4/subscription_entitlements \ -G \ -u {site_api_key}:
curl https://{site}.chargebee.com/api/v2/subscriptions/JzDnHhSBWlm1j1n4/subscription_entitlements \ -G \ -u {site_api_key}:
Enables or disables specific subscription_entitlements
for a subscription.
# 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"
# 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"
subscription_entitlements
are to be enabled or disabled.