Item entitlements

API Version

Product Catalog

Library

Deprecated

The Item Entitlements API is deprecated and no longer maintained. Migrate your integration to Entitlements API.

Warning

API operations listed on this page are not supported when grandfathering is enabled.

Items represent the products or services that you offer to your customers. Items often differ from each other in the product features that are available in them. An item entitlement object represents the entitlement an item has towards a feature. An item can have multiple such entitlements, each corresponding to a unique feature it is entitled to.

Item entitlements can be created while creating a feature. All subscriptions containing an item also inherit its entitlements.

Sample item entitlement [ JSON ]

{
    "item_entitlement": {
        "feature_id": "fea-38eae836-73b4-4056-9704-254818d145de",
        "feature_name": "Quickbooks Integration_123",
        "id": "item-ent-56a6f379-f8e1-44f7-9e83-a7d57522fa1b",
        "item_id": "enterprise",
        "item_type": "plan",
        "name": "Available",
        "object": "item_entitlement",
        "value": "true"
    }
}

API Index URL

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

id

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

item_id

optional, string, max chars=100
The id of the item to which this entitlement belongs.

item_type

optional, enumerated string
The type of the item to which this entitlement belongs.

Possible values are

feature_id

optional, string, max chars=50
The id of the feature towards which this entitlement has been granted.

feature_name

optional, string, max chars=50
The name of the feature towards which this entitlement has been granted.

value

optional, string, max chars=50
The level of entitlement that the item 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 also 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 default values are auto-generated based on feature.type as follows:

When feature.type is quantity or range, then name is the space-separated concatenation of value and the pluralized version of feature.unit. For example, if value is 20 and feature.unit is user, then name becomes 20 users.
When feature.type is custom, then name is the same as 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 item_entitlement. This is auto-generated.

item_id

optional, string, max chars=100
The id of the item to which this entitlement belongs.

item_type

optional, enumerated string
The type of the item to which this entitlement belongs.

Possible values are

feature_id

optional, string, max chars=50
The id of the feature towards which this entitlement has been granted.

feature_name

optional, string, max chars=50
The name of the feature towards which this entitlement has been granted.

value

optional, string, max chars=50
The level of entitlement that the item 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 also 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 default values are auto-generated based on feature.type as follows:

When feature.type is quantity or range, then name is the space-separated concatenation of value and the pluralized version of feature.unit. For example, if value is 20 and feature.unit is user, then name becomes 20 users.
When feature.type is custom, then name is the same as 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

Deprecated

This operation is deprecated and no longer maintained. Migrate your integration to List entitlements.

Retrieves a list of all the item_entitlements for the item specified.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

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

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

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

URL Format GET

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

item_entitlement

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

Deprecated

This operation is deprecated and no longer maintained. Migrate your integration to List entitlements.

Retrieves a list of all the item_entitlements for the feature specified.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/features/fea-66ee05d2-2800-449f-a418-eaa863a67f9f/item_entitlements \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=2 \
     --data-urlencode offset="0"

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

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

URL Format GET

https://{site}.chargebee.com/api/v2/features/{feature-id}/item_entitlements

limit[]

optional, integer, default=10, min=1, max=100
The number of resources to be returned.

offset[]

item_entitlement

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

Deprecated

This operation is deprecated and no longer maintained. Migrate your integration to Manage entitlements.

Warning

This operation is not supported when grandfathering is enabled.

Upserts or removes a set of item_entitlements for an feature depending on the action specified. The API returns the upserted or deleted item_entitlements after successfully completing the operation. The operation returns an error when the first item_entitlement fails to be processed. Either all the item_entitlements provided in the request are processed or none.

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/features/fea-38eae836-73b4-4056-9704-254818d145de/item_entitlements \
     -X POST  \
     -u {site_api_key}:\
     -d action="UPSERT" \
     -d "item_entitlements[value][0]"="true" \
     -d "item_entitlements[item_id][0]"="enterprise" \
     -d "item_entitlements[item_type][0]"="PLAN"

curl  https://{site}.chargebee.com/api/v2/features/fea-51f6e581-2738-47f5-ac08-55f90122f6e2/item_entitlements \
     -X POST  \
     -u {site_api_key}:\
     -d action="REMOVE" \
     -d "item_entitlements[value][0]"="true" \
     -d "item_entitlements[item_id][0]"="enterprise" \
     -d "item_entitlements[item_type][0]"="PLAN"

copy

Click to Copy

Adding item entitlements for a feature

Removal of item entitlements from a feature

200:

STATUS

Sample Response [ JSON ]

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

URL Format POST

https://{site}.chargebee.com/api/v2/features/{feature-id}/item_entitlements

action[]

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

Possible values are

item_entitlements

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

item_entitlements[item_id][0..n]

required, string, max chars=100

item_entitlements[item_type][0..n]

optional, enumerated string

Possible values are

item_entitlements[value][0..n]

optional, string, max chars=50

item_entitlement

always returned
Resource object representing item_entitlement

Try in API Explorer

Deprecated

This operation is deprecated and no longer maintained. Migrate your integration to Manage entitlements.

Warning

This operation is not supported when grandfathering is enabled.

Upserts or removes a set of item_entitlements for an item depending on the action specified. The API returns the upserted or deleted item_entitlements after successfully completing the operation. The operation returns an error when the first item_entitlement fails to be processed. Either all the item_entitlements provided in the request are processed or none.

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/items/basic/item_entitlements \
     -X POST  \
     -u {site_api_key}:\
     -d action="UPSERT" \
     -d "item_entitlements[value][0]"="true" \
     -d "item_entitlements[feature_id][0]"="fea-2959f91d-a517-4440-a7d0-b00cf2fcec62"

curl  https://{site}.chargebee.com/api/v2/items/enterprise/item_entitlements \
     -X POST  \
     -u {site_api_key}:\
     -d action="REMOVE" \
     -d "item_entitlements[feature_id][0]"="fea-3be1c4bf-cd37-4c93-adf5-823db1db3130"

copy

Click to Copy

Adding item entitlements for an item

Remove item entitlements for an item

200:

STATUS

Sample Response [ JSON ]

{
    "list": [
        {
            "item_entitlement": {
                "feature_id": "fea-2959f91d-a517-4440-a7d0-b00cf2fcec62",
                "feature_name": "Quickbooks Integration_aie",
                "id": "item-ent-50a3657a-1452-4f7f-bb50-a8e5ac0a9907",
                "item_id": "basic",
                "item_type": "plan",
                "name": "Available",
                "object": "item_entitlement",
                "value": "true"
            }
        },
        {..}
    ]
}

URL Format POST

https://{site}.chargebee.com/api/v2/items/{item-id}/item_entitlements

action[]

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

Possible values are

item_entitlements

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

item_entitlements[feature_id][0..n]

required, string, max chars=50

item_entitlements[value][0..n]

optional, string, max chars=50

item_entitlement

always returned
Resource object representing item_entitlement

Sample item entitlement [ JSON ]

API Index URL

Model Class

Item entitlement attributes

Event types

Consent Fields for Item entitlement

Custom Fields for Item entitlement

List item entitlements for an item ¶

Notes

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

List item entitlements for a feature ¶

Notes

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

Upsert or remove item entitlements for a feature ¶

Notes

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

Upsert or remove item entitlements for an item ¶

Notes

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