ChargebeeAPI

Entitlement overrides

subscriptions inherit entitlements from items and/or item prices that are in them. Even so, there are many reasons why you may want to override the inherited entitlements on a subscription:

  • A customer wants access to a feature that the items on their subscription are not entitled to.
  • A customer wants a higher feature.level without having to pay more.
  • A customer does not want to see or access a feature because it is irrelevant to them.
  • You offer customized feature bundles for each subscription instead of grouping features into a product catalog of items.

This API helps you implement each of the above use cases, offering a method to override the entitlements for a subscription at the subscription, item price, or charge-item level.

entitlement_override expiry

If expires_at has been set, then the entitlement_override object is no longer returned after expires_at has passed. The expiration of an entitlement_override does not trigger any event immediately. However, after expiry, the entitlement_override record gets deleted within 12 hours. This deletion triggers the entitlement_overrides_auto_removed event which can be considered as a notification, albeit delayed, for one or more entitlement_overrides having expired.

Sample Entitlement overrideJSON

API Index URL

https://[site].chargebee.com/api/v2/entitlement_overrides

Entitlement overrides attributes

id
required, string, max chars=50

Unique identifier for the entitlement override. This is always auto-generated.

subscription_id
optional, string, max chars=50

The id of the subscription to which this entitlement override belongr

entity_id
optional, string, max chars=50

The id of the entity at whose level the entitlement override is being set for the subscription. If the entity_id is not currently a part of the subscription, the entitlement_override takes effect as soon as the entity is added to the subscription.

entity_type
optional, string, max chars=50

The type of the entity at whose level the entitlement override is being set for the subscription.

feature_id
optional, string, max chars=50

The id of the feature for which the entitlement override is being set.

feature_name
optional, string, max chars=50

The name of the feature towards which this entitlement override 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 true if the feature is available; it is set as false when the feature is unavailable.

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.
expires_at
optional, timestamp(UTC) in seconds

The expiry date for the entitlement_override. The entitlement_override object is no longer returned after this date has passed.

effective_from
optional, timestamp(UTC) in seconds
is_enabled
required, boolean