Subscription entitlements

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.

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:

Switch feature

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.

Quantity feature

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.

Range feature

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

Custom feature

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": "Azq8g8ULPXqdL6zM",
        "feature_id": "xero-integration",
        "feature_name": "Xero Integration",
        "feature_type": "SWITCH",
        "value": "true",
        "name": "Available",
        "is_overridden": true,
        "is_enabled": true,
        "object": "subscription_entitlement"
    }
}

API Index URL

https://{site}.chargebee.com/api/v2/subscription_entitlements

subscription_id

string, max chars=50
The unique identifier of the subscription.

feature_id

optional, string, max chars=50
The unique identifier of the feature.

feature_name

optional, string, max chars=50
The name of the feature.

feature_unit

optional, string, max chars=50
The unit of measure for the feature when its type is either quantity or range.

feature_type

optional, string, max chars=50
Specifies the type of the feature associated with the granted subscription entitlement.

value

optional, string, max chars=50

The value denoting the final entitlement level that the subscription holds for the feature.

name

optional, string, max chars=50
The display name of the final entitlement level that the subscription holds for the feature. 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 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 set to Available when value is true; it's set to Not Available when value is false.

is_overridden

boolean
Indicates whether the entitlement held by the subscription for the feature is overridden via an entitlement_overrides record.

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

subscription_id

string, max chars=50
The unique identifier of the subscription.

feature_id

optional, string, max chars=50
The unique identifier of the feature.

feature_name

optional, string, max chars=50
The name of the feature.

feature_unit

optional, string, max chars=50
The unit of measure for the feature when its type is either quantity or range.

feature_type

optional, string, max chars=50
Specifies the type of the feature associated with the granted subscription entitlement.

value

optional, string, max chars=50

The value denoting the final entitlement level that the subscription holds for the feature.

name

optional, string, max chars=50
The display name of the final entitlement level that the subscription holds for the feature. 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 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 set to Available when value is true; it's set to Not Available when value is false.

is_overridden

boolean
Indicates whether the entitlement held by the subscription for the feature is overridden via an entitlement_overrides record.

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

optional, component
The component entitlements that constitute this subscription_entitlement. The effective entitlement value and name are determined from these component entitlements.

Try in API Explorer

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

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/subscriptions/JzDnHhSBWlm1j1n4/subscription_entitlements \
     -G  \
     -u {site_api_key}:

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

{
    "list": [
        {
            "subscription_entitlement": {
                "subscription_id": "Azq8g8ULPXqdL6zM",
                "feature_id": "xero-integration",
                "feature_name": "Xero Integration",
                "feature_type": "SWITCH",
                "value": "true",
                "name": "Available",
                "is_overridden": true,
                "is_enabled": true,
                "object": "subscription_entitlement"
            }
        },
        {..}
    ]
}

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

Try in API Explorer

Enables or disables specific subscription_entitlements for a subscription.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

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

To enable/disable features for a subscription

200:

STATUS

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

subscription_entitlement

always returned
Resource object representing subscription_entitlement

Overview

How subscription entitlements are determined

Switch feature

Summary

Example

1. Feature record

2. Entitlement records

3. Subscription-items records

4. Subscription-item entitlements

5. Determining final subscription entitlements

Case 1: Absence of a subscription-level override

Case 2: With subscription-level override

Quantity feature

Summary

Example

1. Feature record

2. Entitlement records

3. Subscription-items records

4. Subscription-item entitlements

5. Determining final subscription entitlements

Case 1: Absence of a subscription-level override

Case 2: With subscription-level override

Range feature

Summary

Example

1. Feature record

2. Entitlement records

3. Subscription-items records

4. Subscription-item entitlements

5. Determining final subscription entitlements

Case 1: feature.levels[1].is_unlimited is false

Case 2: feature.levels[1].is_unlimited is true

Custom feature

Summary

Example

1. Feature record

2. Entitlement records

3. Subscription-items records

4. Subscription-item entitlements

5. Determining final subscription entitlements

Case 1: Absence of a subscription-level override

Case 2: With subscription-level override

Sample subscription entitlement [ JSON ]

API Index URL

Model Class

Subscription entitlement attributes

Consent Fields for Subscription entitlement

Custom Fields for Subscription entitlement

List subscription entitlements ¶

Sample Response [ JSON ]

URL Format GET

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

Enable or disable subscription entitlements ¶

Sample Response [ JSON ]

URL Format POST

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

Case 1: `feature.levels[1].is_unlimited` is `false`

Case 2: `feature.levels[1].is_unlimited` is `true`