POST /entitlements

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 subscriptions {#grandfathering}

Early Access

Grandfathering support for 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.

Servers

{protocol}://{site}.{environment}:{port}/api/v2
{protocol}://{site}-test.{environment}:{port}/api/v2

Request headers

Name	Type	Required	Description
`chargebee-request-origin-device`	String	No	The device from which the customer has made the request
`Content-Type`	String	Yes	The media type of the request body. Default value: "application/x-www-form-urlencoded"
`chargebee-event-webhook`	String	No	skip only webhooks Possible values: `"all-disabled"`
`chargebee-business-entity-id`	String	No	If the site has multiple business entities, you can use this custom HTTP header to specify the business entity for which Chargebee should perform the operation.
`chargebee-event-actions`	String	No	skip all actions to be done on the events Possible values: `"all-disabled"`
`chargebee-request-origin-user`	String	No	The email address of your customer/user. Use this when the email address has only ASCII characters.
`chargebee-request-origin-ip`	String	No	The IP address of the customer where the request originated
`chargebee-request-origin-user-encoded`	String	No	The Base64-encoded email address of your customer/user. Use this if the email address has UTF-8 characters. When this header is provided, the header `chargebee-request-origin-user` is ignored.
`chargebee-event-email`	String	No	skip only emails Possible values: `"all-disabled"`

Request body fields

Name	Type	Required	Description
`action`	String	Yes	The specific action to be performed for each `entitlement` specified. * upsert - If the `entitlement` already exists for the `feature_id` and `entity_id` combination, the `value` of the `entitlement` is updated. If it doesn't exist, a new `entitlement` is created. * remove - Deletes the `entitlement` for the `feature_id` and `entity_id` combination, if it exists. Possible values: `"remove"` `"upsert"`
`change_reason`	String	No	Comments or reason for this entitlement change.
`entitlements`	Object	No	Parameters for entitlements
`entitlements.entity_id[]`	Array	Yes	The unique identifier of the entity being granted entitlement to a specific `feature`. Note In the case of an `upsert` `action`, if the `entitlement` resource does not already exist, Chargebee does not validate this ID to confirm its correspondence to an existing entity. The `entitlement` is created regardless.
`entitlements.apply_grandfathering[]`	Array	No	Early Access Grandfathering support for entitlements is in early access. Write to eap@chargebee.com to get this enabled. Determines whether to grandfather in existing subscriptions affected by this entitlement. `true`: Existing subscriptions that contain this entity as one of the subscription items, are not mapped to this value of the entitlement; their currently mapped value for this entitlement are retained. New subscriptions created in the future that contain this entity, or existing subscriptions updated in the future to include this entity, are mapped to this value of the entitlement. `false`: All subscriptions that contain this entity are mapped to this version of the entitlement.
`entitlements.value[]`	Array	No	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`.
`entitlements.feature_id[]`	Array	Yes	The unique identifier of the `feature` to which the entity gains entitlement.
`entitlements.entity_type[]`	Array	No

How to start integrating

Add HTTP Task to your workflow definition.
Search for the API you want to integrate with and click on the name.
- This loads the API reference documentation and prepares the Http request settings.
Click Test request to test run your request to the API and see the API's response.