Entitlements

API Version

Product Catalog

Library

The entitlement resource establishes a connection between a feature and an item or an item_price in Chargebee Billing. By defining this relationship, it specifies the scope of access or rights the item or item price has in relation to that particular feature.

Sample entitlement [ JSON ]

{
    "entitlement": {
        "feature_id": "fea-66ee05d2-2800-449f-a418-eaa863a67f9f",
        "feature_name": "Quickbooks Integration_1234",
        "id": "ent-15292c03-0b77-426a-aa5b-a18bb0acafdc",
        "entity_id": "enterprise",
        "entity_type": "plan",
        "name": "Available",
        "object": "entitlement",
        "value": "true"
    }
}

API Index URL

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

id

string, max chars=100
A unique identifier for the entitlement. This is auto-generated.

entity_id

optional, string, max chars=100

The unique identifier of the entity being granted entitlement to a specific feature.

entity_type

optional, enumerated string
The type of the entity that holds this entitlement.

Possible values are

feature_id

optional, string, max chars=50

The unique identifier of the feature to which the entity gains entitlement.

feature_name

optional, string, max chars=50
The name of the feature associated with this entitlement.

value

optional, string, max chars=50
The level of entitlement that the entity has towards the feature. The possible values depend on the value of feature.type:

When feature.type is quantity and:

If feature.levels[is_unlimited] is not true for any one of feature.levels[], then the value can be any one of feature.levels[value][].
If feature.levels[is_unlimited] is true for one of the feature.levels[], then the value can be:
- any one of feature.levels[value][]
- or it can be unlimited (case-insensitive), indicating unlimited entitlement.

When type is range and:

If feature.levels[is_unlimited] is not true for any one of feature.levels[], then the value can be any whole number between levels[value][0] and levels[value][1] (inclusive).
If feature.levels[is_unlimited] is true for one of the feature.levels[], then the value can be:
- any whole number equal to or greater than levels[value][0]
- or it can be unlimited (case-insensitive), indicating unlimited entitlement.

When type is custom, then the value can be any one of feature.levels[value][].
When type is switch, then the value is set as available or true.

name

optional, string, max chars=50

The display name for the entitlement level. The value is automatically generated based on feature.type:

When feature.type is quantity or range, the name is the space-separated concatenation of value and the plural form of feature.unit. For instance, if value is 20 and feature.unit is user, the name will be 20 users.
When feature.type is custom, the name matches the value.
When feature.type is switch, the name is set to Available when value is true; it's set to Not Available when value is false.

id

string, max chars=100
A unique identifier for the entitlement. This is auto-generated.

entity_id

optional, string, max chars=100

The unique identifier of the entity being granted entitlement to a specific feature.

entity_type

optional, enumerated string
The type of the entity that holds this entitlement.

Possible values are

feature_id

optional, string, max chars=50

The unique identifier of the feature to which the entity gains entitlement.

feature_name

optional, string, max chars=50
The name of the feature associated with this entitlement.

value

optional, string, max chars=50
The level of entitlement that the entity has towards the feature. The possible values depend on the value of feature.type:

When feature.type is quantity and:

If feature.levels[is_unlimited] is not true for any one of feature.levels[], then the value can be any one of feature.levels[value][].
If feature.levels[is_unlimited] is true for one of the feature.levels[], then the value can be:
- any one of feature.levels[value][]
- or it can be unlimited (case-insensitive), indicating unlimited entitlement.

When type is range and:

If feature.levels[is_unlimited] is not true for any one of feature.levels[], then the value can be any whole number between levels[value][0] and levels[value][1] (inclusive).
If feature.levels[is_unlimited] is true for one of the feature.levels[], then the value can be:
- any whole number equal to or greater than levels[value][0]
- or it can be unlimited (case-insensitive), indicating unlimited entitlement.

When type is custom, then the value can be any one of feature.levels[value][].
When type is switch, then the value is set as available or true.

name

optional, string, max chars=50

The display name for the entitlement level. The value is automatically generated based on feature.type:

When feature.type is quantity or range, the name is the space-separated concatenation of value and the plural form of feature.unit. For instance, if value is 20 and feature.unit is user, the name will be 20 users.
When feature.type is custom, the name matches the value.
When feature.type is switch, the name is set to Available when value is true; it's set to Not Available when value is false.

Try in API Explorer

Retrieves a list of all the entitlements associated with the specified feature.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/entitlements \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=2 \
     --data-urlencode offset="0"

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

{
    "list": [
        {
            "entitlement": {
                "feature_id": "fea-66ee05d2-2800-449f-a418-eaa863a67f9f",
                "feature_name": "Quickbooks Integration_1234",
                "id": "ent-15292c03-0b77-426a-aa5b-a18bb0acafdc",
                "entity_id": "enterprise",
                "entity_type": "plan",
                "name": "Available",
                "object": "entitlement",
                "value": "true"
            }
        },
        {..}
    ]
}

URL Format GET

https://{site}.chargebee.com/api/v2/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.

Filter Params

For operator usages, see the Pagination and Filtering section.

feature_id[<operator>]

optional, string filter
The id of the feature associated with this entitlement.
Supported operators : is, in

Example → feature_id[is] = "user-licenses"

entity_type[<operator>]

optional, enumerated string filter
The type of the entity to which this entitlement belongs. Possible values are : plan, addon, charge, plan_price, addon_price
Supported operators : is, in

Example → entity_type[is] = "plan_price"

entity_id[<operator>]

optional, string filter
The id of the entity to which this entitlement belongs. .
Supported operators : is, in

Example → entity_id[is] = "usd-professional-monthly"

entitlement

always returned
Resource object representing 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

Create, update, or remove a set of entitlements for a feature.

The behavior depends on the specified action. It tries to create, update, or delete entitlement objects. If any of the entitlement objects fail to process, the entire operation stops with an error, and no entitlements are processed. In essence, the request processes either all the provided entitlements or none of them.

Grandfathering in entitlements

Early Access

Grandfathering in entitlements is in early access. Write to eap@chargebee.com to get this enabled.

By default, this operation impacts all subscriptions that contain the item or item price. However, if you set apply_grandfathering to true, the existing subscriptions are not impacted by the change.

Example

Consider the following example:

On January 1st

You have a plan price (id: premium-monthly-usd) entitled to a feature (user_licenses) at value 10.
You have a subscription (id: AzZjAiTl1btqS2lEj) that contains the plan price (premium-monthly-usd).

On January 2nd

Using this API operation, you change the entitlement level of the plan price premium-monthly-usd for the user_licenses feature to value 20. You also set apply_grandfathering to true.
After the API operation completes, you create a new subscription (id: 6oqNGUlMd9Yn4Ui) that contains the same plan price (premium-monthly-usd).
The existing subscription (id: AzZjAiTl1btqS2lEj) is grandfathered in, so it continues to be entitled to user_licenses at value 10. The new subscription (id: 6oqNGUlMd9Yn4Ui) is entitled to user_licenses at value 20.

On January 3rd

Using this API operation, you change the entitlement level of the plan price premium-monthly-usd for the user_licenses feature to value 30. You also set apply_grandfathering to false.
After the API operation completes, you create another subscription (id: 99CRh8UgMXTq77tl) that contains the same plan price (premium-monthly-usd).
Because grandfathering was not enabled, all three subscriptions (AzZjAiTl1btqS2lEj, 6oqNGUlMd9Yn4Ui, and 99CRh8UgMXTq77tl) are now entitled to user_licenses at value 30.

Sample Request

Try in API Explorer

Only for Java

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/entitlements \
     -u {site_api_key}:\
     -d action="UPSERT" \
     -d "entitlements[value][0]"="true" \
     -d "entitlements[feature_id][0]"="fea-2959f91d-a517-4440-a7d0-b00cf2fcec62" \
     -d "entitlements[entity_id][0]"="enterprise" \
     -d "entitlements[entity_type][0]"="PLAN"

curl  https://{site}.chargebee.com/api/v2/entitlements \
     -u {site_api_key}:\
     -d action="REMOVE" \
     -d "entitlements[feature_id][0]"="fea-2959f91d-a517-4440-a7d0-b00cf2fcec62" \
     -d "entitlements[entity_id][0]"="enterprise" \
     -d "entitlements[entity_type][0]"="PLAN"

copy

Click to Copy

Adding entitlements for a feature

Removal of entitlements from a feature

200:

STATUS

Sample Response [ JSON ]

{
    "list": [
        {
            "entitlement": {
                "feature_id": "fea-38eae836-73b4-4056-9704-254818d145de",
                "feature_name": "Quickbooks Integration_123",
                "id": "ent-56a6f379-f8e1-44f7-9e83-a7d57522fa1b",
                "entity_id": "enterprise",
                "entity_type": "plan",
                "name": "Available",
                "object": "entitlement",
                "value": "true"
            }
        },
        {..}
    ]
}

URL Format POST

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

action[]

required, enumerated string
The specific action to be performed for each entitlement specified.

Possible values are

change_reason[]

optional, string, max chars=100
Comments or reason for this entitlement change.

entitlements

Parameters for entitlements. Multiple entitlements can be passed by specifying unique indices.
pass parameters as entitlements[<param name>][<idx:0..n>]

entitlements[entity_id][0..n]

required, string, max chars=100

entitlements[feature_id][0..n]

required, string, max chars=50

entitlements[entity_type][0..n]

optional, enumerated string

Possible values are

entitlements[value][0..n]

optional, string, max chars=50

entitlements[apply_grandfathering][0..n]

optional, boolean, default=false

entitlement

always returned
Resource object representing entitlement

Sample entitlement [ JSON ]

API Index URL

Model Class

Entitlement attributes

Consent Fields for Entitlement

Custom Fields for Entitlement

List 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

Manage entitlements for a feature ¶

Grandfathering in entitlements

Example

On January 1st

On January 2nd

On January 3rd

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