This API remains operational, but we recommend transitioning to its successor: Entitlements API.
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.
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.
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.a
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.
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.a
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.
always returned 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`.
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.
always returned 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`.
Upsert or remove item entitlements for a feature
¶
Idempotency Supported
Deprecated
This endpoint remains operational, but we recommend transitioning to its successor: Manage entitlements.
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.
This API is not enabled for live sites by default. Please contact
support to get this enabled.
Notes
Sample Request
# Adding item entitlements for a feature
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"
# Removal of item entitlements from a feature
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"
required, enumerated string The specific action to be performed for each item_entitlement specified.
Possible values are
upsertIf the item_entitlement already exists for the feature_id and item_id combination, the value of the item_entitlement is updated. If it doesn’t exist, a new item_entitelment is created.removeDeletes the item_entitlement for the feature_id and item_id combination, if it exists.
Parameters for item_entitlements. Multiple item_entitlements can be passed by specifying unique indices. pass parameters as item_entitlements[<param name>][<idx:0..n>]
This endpoint remains operational, but we recommend transitioning to its successor: Manage entitlements.
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.
This API is not enabled for live sites by default. Please contact
support to get this enabled.
Notes
Sample Request
# Adding item entitlements for an item
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"
# Remove item entitlements for an item
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"
required, enumerated string The specific action to be performed for each item_entitlement specified.
Possible values are
upsertIf the item_entitlement already exists for the feature_id and item_id combination, the value of the item_entitlement is updated. If it doesn’t exist, a new item_entitelment is created.removeDeletes the item_entitlement for the feature_id and item_id combination, if it exists.
Parameters for item_entitlements. Multiple item_entitlements can be passed by specifying unique indices. pass parameters as item_entitlements[<param name>][<idx:0..n>]