API Version
Product Catalog
Library

Overview

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.

How subscription entitlements are determined

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 entitlements linked to the item_prices 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 entitlements follows specific rules determined by the feature type. We outline and provide examples of these rules in the sections below:

Summary

Consider a feature of type switch. Consider also a subscription, some of whose subscription_items correspond to item_prices (or items) that have entitlements 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 true, then the subscription_entitlement value is also set to true. Otherwise, the subscription_entitlement value is also set to false.

Example

1. Feature record

Consider the following feature record:

Table 1: feature records.

id

type

description

xero-integration

switch

An integration with the Xero accounting software.

2. Entitlement records

Consider the following entitlement records for the xero-integration feature:

Table 2: entitlement records for the xero-integration feature.

entity_id

entity_type

value

starter

plan

true

starter-monthly-usd

plan_price

false

plus

addon

true

3. Subscription-items records

Consider that a subscription with id AzZjAiTl1btqS2lEj has the following subscription.subscription_items[] records:

Table 3: subscription.subscription_items[] records.
subscription_items[] index

item_price_id

quantity

0

starter-monthly-usd

1

1

plus-monthly-usd

1

2

installation-usd

2

4. Subscription-item entitlements

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.

Table 4: Entitlement values for subscription.subscription_items[].
subscription_items[] index

item_price_id

Entitlement value (determined from Table 2)

0

starter-monthly-usd

false

(Matches the value of the plan price.)

1

plus-monthly-usd

true

(Inherited from the addon plus, as no entitlement is defined for this addon price.)

2

installation-usd

None

(No entitlement defined for the charge item.)

5. Determining final subscription entitlements
Case 1: Absence of a subscription-level override

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.

Case 2: With subscription-level override

Suppose there's an entitlement_override added to the subscription for the feature, as shown below:

Table 5: entitlement_override record for the subscription and feature.

entity_id

entity_type

feature_id

value

AzZjAiTl1btqS2lEj

subscription

xero-integration

false

Given this override, the subscription's final entitlement value (subscription_entitlement.value) for the xero-integration feature is set to false.

Summary

Consider a feature of type quantity. Consider also a subscription, some of whose subscription_items correspond to item_prices (or items) that have entitlements 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.

Example

1. Feature record

Consider the following feature record:

Table 6: feature records.

id

type

description

user_licenses

quantity

The number of user licenses provided.

Suppose that the feature has feature.levels[] records as follows:

Table 7: feature.levels[] records.

levels[].level

levels[].value

levels[].is_unlimited

0

5

false

1

10

false

2

20

false

3

Not set.

true

2. Entitlement records

Consider the following entitlement records for the user_licenses feature:

Table 8: entitlement records for the user_licenses feature.

entity_id

entity_type

value

starter

plan

10

starter-monthly-usd

plan_price

unlimited

plus

addon

5

one-time

charge

5

3. Subscription-items records

Consider that a subscription with id AzZjAiTl1btqS2lEj has the following subscription.subscription_items[] records:

Table 9: subscription.subscription_items[] records.
subscription_items[] index

item_price_id

quantity

0

starter-monthly-usd

5

1

plus-monthly-usd

10

2

one-time-usd

1

4. Subscription-item entitlements

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.

Table 10: Entitlement values for subscription.subscription_items[].
subscription_items[] index item_price_id quantity Entitlement value (determined from Table 8) Entitlement value subtotal (Entitlement value x quantity)

0

starter-monthly-usd

5

unlimited

(Matches the value of the plan price.)

unlimited (unlimited x 5)

1

plus-monthly-usd

10

5

(Inherited from the addon plus, as no entitlement is defined for this addon price.)

50 (5 x 10)

2

one-time-usd

1

5

(Inherited from the charge one-time.)

5 (5 x 1)

5. Determining final subscription entitlements
Case 1: Absence of a subscription-level override

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.

Case 2: With subscription-level override

Suppose there's an entitlement_override added to the subscription for the feature, as shown below:

Table 11: entitlement_override record for the subscription and feature.

entity_id

entity_type

feature_id

value

AzZjAiTl1btqS2lEj

subscription

user_licenses

20

Given this override, the subscription's final entitlement value (subscription_entitlement.value) for the user-licenses feature is set to 20.

Summary

Consider a feature of type range. Consider also a subscription, some of whose subscription_items correspond to item_prices (or items) that have entitlements 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.

Example

1. Feature record

Consider the following feature record:

Table 12: feature records.

id

type

description

api_rate_limit

range

The maximum number of API requests allowed per minute.

Suppose that the feature has feature.levels[] records as follows:

Table 13: feature.levels[] records.

levels[].level

levels[].value

levels[].is_unlimited

0

100

false

1

1000

false

2. Entitlement records

Consider the following entitlement records for the api_rate_limit feature:

Table 14: entitlement records for the api_rate_limit feature.

entity_id

entity_type

value

premium

plan

450

premium-monthly-usd

plan_price

400

plus

addon

150

3. Subscription-items records

Consider that a subscription with id AzZjAiTl1btqS2lEj has the following subscription.subscription_items[] records:

Table 15: subscription.subscription_items[] records.
subscription_items[] index

item_price_id

quantity

0

premium-monthly-usd

2

1

plus-monthly-usd

2

4. Subscription-item entitlements

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.

Table 16: Entitlement values for subscription.subscription_items[].
subscription_items[] index

item_price_id

quantity

Entitlement value (determined from Table 14) Entitlement value subtotal (Entitlement value x quantity)

0

premium-monthly-usd

2

400

(Matches the value of the plan price.)

800 (400 x 2)

1

plus-monthly-usd

2

150

(Inherited from the addon plus, as no entitlement is defined for this addon price.)

300 (150 x 2)

5. Determining final subscription entitlements
Case 1: 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.

Case 2: 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.

Summary

Consider a feature of type custom. Consider also a subscription, some of whose subscription_items correspond to item_prices (or items) that have entitlements 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.

Example

1. Feature record

Consider the following feature record:

Table 17: feature records.

id

type

description

support

custom

The form of after-sales support provided to the customer.

Suppose that the feature has feature.levels[] records as follows:

Table 18: feature.levels[] records.

levels[].level

levels[].value

0

email

1

chat

2

call

2. Entitlement records

Consider the following entitlement records for the support feature:

Table 19: entitlement records for the api_rate_limit feature.

entity_id

entity_type

value

starter

plan

chat

starter-monthly-usd

plan_price

email

plus

addon

call

3. Subscription-items records

Consider that a subscription with id AzZjAiTl1btqS2lEj has the following subscription.subscription_items[] records:

Table 20: subscription.subscription_items[] records.
subscription_items[] index

item_price_id

quantity

0

starter-monthly-usd

2

1

plus-monthly-usd

2

4. Subscription-item entitlements

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.

Table 21: Entitlement values for subscription.subscription_items[].
subscription_items[] index

item_price_id

Subscription-Item Entitlement Value (determined from Table )

0

starter-monthly-usd

email

(Matches the value of the plan price.)

1

plus-monthly-usd

call

(Inherited from the addon plus, as no entitlement is defined for this addon price.)

5. Determining final subscription entitlements
Case 1: Absence of a subscription-level override

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.

Case 2: With subscription-level override

Suppose there's an entitlement_override added to the subscription for the feature, as shown below:

Table 22: entitlement_override record for the subscription and feature.

entity_id

entity_type

feature_id

value

expires_at

AzZjAiTl1btqS2lEj

subscription

support

chat

1695884985 (7 days from now, assuming today is 2023-09-21.)

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.

Sample subscription entitlement [ JSON ]

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

Model Class

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.
optional, component
The component entitlements that constitute this subscription_entitlement. The effective entitlement value and name are determined from these component entitlements.
subscription_id subscription_id
string, max chars=50
The id of the subscription to which this entitlement belongs.
feature_id feature_id
optional, string, max chars=50
The id of the feature towards which this subscription entitlement has been granted.
feature_name feature_name
optional, string, max chars=50
The name of the feature towards which this subscription entitlement has been granted.
feature_unit feature_unit
optional, string, max chars=50
The unit of measure for the feature when its type is either quantity or range.
value 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 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 is_overridden
boolean
Indicates that components.entitlement_overrides exists.
is_enabled is_enabled
boolean
Indicates that components.is_enabled exists.
expires_at expires_at
optional, timestamp(UTC) in seconds
Timestamp when the subscription entitlements are going to expire.
components
optional, component
The component entitlements that constitute this subscription_entitlement. The effective entitlement value and name are determined from these component entitlements.

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.

Notes

Sample Request
curl  https://{site}.chargebee.com/api/v2/subscriptions/JzDnHhSBWlm1j1n4/subscription_entitlements \
     -G  \
     -u {site_api_key}:
copy
Click to Copy

Sample Response [ JSON ]

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

Method

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 subscription_entitlement
always returned
Resource object representing subscription_entitlement
next_offset 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 admin console URL

https://{site}.chargebee.com/admin-console/subscription_entitlements/123x

Enables or disables specific subscription_entitlements for a subscription.

Notes

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
Click to Copy

Sample Response [ JSON ]

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

Method

is_enabled[]
required, boolean
Specifies whether the subscription_entitlements are to be enabled or disabled.
subscription_entitlements[feature_id][0..n]
required, string, max chars=50
subscription_entitlement subscription_entitlement
always returned
Resource object representing subscription_entitlement

Sample admin console URL

https://{site}.chargebee.com/admin-console/subscription_entitlements/123x