ChargebeeAPI

Manage entitlements for a feature

Idempotency Supported
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

URL Format

POST https://[site].chargebee.com/api/v2/entitlements

Input Parameters

action
required, enumerated string

The specific action to be performed for each entitlement specified.

Possible Enum Values
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.

change_reason
optional, string, max chars=100

Comments or reason for this entitlement change.

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

Returns

entitlementEntitlement object
Resource object representing entitlement