The subscription_entitlement
object represents the entitlement a subscription
holds for a feature
. A subscription can have several subscription_entitlements
, each tied to a specific feature. The diagram that follows illustrates the relationship between subscription_entitlement
and other Entitlements API objects.
When an entitlement_override
is set for a subscription related to a feature, the value of the subscription_entitlement
takes on the value
of the entitlement_override
.
If there isn't an entitlement_override
, the value of the subscription_entitlement
is based on the entitlement
s linked to the item_price
s within the subscription_items
. If an item_price
lacks an entitlement record for a particular feature, we consider the entitlement (when available) of its parent item
.
The method used to derive the subscription_entitlement
from entitlement
s follows specific rules determined by the feature type
. We outline and provide examples of these rules in the sections below:
Consider a feature
of type switch
. Consider also a subscription
, some of whose subscription_item
s correspond to item_price
s (or item
s) that have entitlement
s to the feature. Looking at these entitlements, we first determine the entitlement value held by each subscription_item
for this feature.
If the entitlement value for the feature held by any of the subscription_item
s is true
, then the subscription_entitlement
value
is also set to true
. Otherwise, the subscription_entitlement
value
is also set to false
.
Consider the following feature
record:
|
|
|
---|---|---|
|
|
|
Consider the following entitlement
records for the xero-integration
feature:
|
|
|
---|---|---|
|
|
|
|
|
|
|
|
|
Consider that a subscription
with id
AzZjAiTl1btqS2lEj
has the following subscription.subscription_items[]
records:
subscription_items[] index |
|
|
---|---|---|
|
|
|
|
|
|
|
|
|
Chargebee Billing now determines the entitlement held by each subscription_items[]
based on the entitlements defined in Table 2. This is shown in Table 4. For clarity, we've omitted the quantity
column because it doesn't affect features with the switch
type
.
subscription_items[] index |
|
Entitlement value (determined from Table 2) |
---|---|---|
|
|
(Matches the value of the plan price.) |
|
|
(Inherited from the addon |
|
|
None (No entitlement defined for the charge item.) |
In this scenario, the final entitlement (subscription_entitlement.value
) for the xero-integration
feature is set to true
because at least one subscription-item entitlement value
is true
.
Suppose there's an entitlement_override
added to the subscription for the feature, as shown below:
|
|
|
|
---|---|---|---|
|
|
|
|
Given this override, the subscription's final entitlement value (subscription_entitlement.value
) for the xero-integration
feature is set to false
.
Consider a feature
of type quantity
. Consider also a subscription
, some of whose subscription_items
correspond to item_price
s (or item
s) that have entitlement
s to the feature. Looking at these entitlements, we first determine the entitlement value held by each subscription_item
for this feature.
If the entitlement value for the feature held by any of the subscription_items
is unlimited
, then the subscription_entitlement
value
is also unlimited
. Otherwise, the subscription_entitlement
value
is the sum of all the entitlement values of the subscription_items
.
Consider the following feature
record:
|
|
|
---|---|---|
|
|
|
Suppose that the feature has feature.levels[]
records as follows:
|
|
|
---|---|---|
|
|
|
|
|
|
|
|
|
|
Not set. |
|
Consider the following entitlement
records for the user_licenses
feature:
|
|
|
---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
Consider that a subscription
with id
AzZjAiTl1btqS2lEj
has the following subscription.subscription_items[]
records:
subscription_items[] index |
|
|
---|---|---|
|
|
|
|
|
|
|
|
|
Chargebee Billing now determines the entitlement held by each subscription_items[]
based on the entitlements defined in Table 8. This is shown in Table 10.
subscription_items[] index |
item_price_id |
quantity |
Entitlement value (determined from Table 8) | Entitlement value subtotal (Entitlement value x quantity ) |
---|---|---|---|---|
|
|
|
(Matches the value of the plan price.) |
|
|
|
|
(Inherited from the addon |
|
|
|
|
(Inherited from the charge |
|
In this scenario, the final entitlement value (subscription_entitlement.value
) for the user-licenses
feature is the total entitlement value from the last column in Table 10. Which amounts to (unlimited + 50 + 5) = unlimited
.
Suppose there's an entitlement_override
added to the subscription for the feature, as shown below:
|
|
|
|
---|---|---|---|
|
|
|
|
Given this override, the subscription's final entitlement value (subscription_entitlement.value
) for the user-licenses
feature is set to 20
.
Consider a feature
of type range
. Consider also a subscription
, some of whose subscription_items
correspond to item_price
s (or item
s) that have entitlement
s to the feature. Looking at these entitlements, we first determine the entitlement value held by each subscription_item
for this feature.
If the entitlement value for the feature held by any of the subscription_items
is unlimited
, then the subscription_entitlement
value
is also unlimited
. Otherwise, one of two scenarios are possible:
If feature.levels[1].is_unlimited
is true
, the subscription_entitlement
value
equals the sum of all entitlement values of the subscription_items
.
If feature.levels[1].is_unlimited
is false
, the subscription_entitlement
value
equals the sum of all entitlement values of the subscription_items
without exceeding the maximum value of feature.level[1].value
.
Consider the following feature
record:
|
|
|
---|---|---|
|
|
|
Suppose that the feature has feature.levels[]
records as follows:
|
|
|
---|---|---|
|
|
|
|
|
|
Consider the following entitlement
records for the api_rate_limit
feature:
|
|
|
---|---|---|
|
|
|
|
|
|
|
|
|
Consider that a subscription
with id
AzZjAiTl1btqS2lEj
has the following subscription.subscription_items[]
records:
subscription_items[] index |
|
|
---|---|---|
|
|
|
|
|
|
Chargebee Billing now determines the entitlement held by each subscription_items[]
based on the entitlements defined in Table 14. This is shown in Table 16.
subscription_items[] index |
|
|
Entitlement value (determined from Table 14) |
Entitlement value subtotal (Entitlement value x quantity ) |
---|---|---|---|---|
|
|
|
(Matches the value of the plan price.) |
|
|
|
|
(Inherited from the addon |
|
feature.levels[1].is_unlimited
is false
In this scenario, the final entitlement value (subscription_entitlement.value
) for the api_rate_limit
feature is the total entitlement value from the last column in Table 16, capped at feature.levels[1].value
. The total entitlement value is 800 + 300 equaling 1100. However, feature.levels[1].value
is 1000
, which is less than 1100. Therefore, the final entitlement is 1000
.
feature.levels[1].is_unlimited
is true
In this scenario, feature.levels[1].value
is disregarded, and the final entitlement value (subscription_entitlement.value
) is not capped. In other words, the final entitlement value is 1100
.
Consider a feature
of type custom
. Consider also a subscription
, some of whose subscription_items
correspond to item_price
s (or item
s) that have entitlement
s to the feature.
Looking at these entitlements, we first determine the entitlement value held by each subscription_item
for this feature. The subscription_entitlement
value is then set to the highest of these identified values.
Consider the following feature
record:
|
|
|
---|---|---|
|
|
|
Suppose that the feature has feature.levels[]
records as follows:
|
|
---|---|
|
|
|
|
|
|
Consider the following entitlement
records for the support
feature:
|
|
|
---|---|---|
|
|
|
|
|
|
|
|
|
Consider that a subscription
with id
AzZjAiTl1btqS2lEj
has the following subscription.subscription_items[]
records:
subscription_items[] index |
|
|
---|---|---|
|
|
|
|
|
|
Chargebee Billing now determines the entitlement held by each subscription_items[]
based on the entitlements defined in Table 19. This is shown in Table 21. For clarity, we've omitted the quantity
column because it doesn't affect features with the custom
type
.
subscription_items[] index |
|
Subscription-Item Entitlement Value (determined from Table ) |
---|---|---|
|
|
(Matches the value of the plan price.) |
|
|
(Inherited from the addon |
In this scenario, the final entitlement (subscription_entitlement.value
) for the support
feature is the highest of all the subscription-item entitlement values, which in this case is call
.
Suppose there's an entitlement_override
added to the subscription for the feature, as shown below:
|
|
|
|
|
---|---|---|---|---|
|
|
|
|
|
Given this override, the subscription's final entitlement value (subscription_entitlement.value
) for the support
feature will be chat
until 2023-09-21 and call
thereafter.
{
"subscription_entitlement": {
"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.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}:
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"