ChargebeeAPI
Join the Chargebee Developers Discord — Connect, ask questions, and build faster.Join

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 belongs.

entity_id
optional, string, max chars=50
  • When omitted, the entitlement override applies at the subscription level. See subscription-level entitlement overrides.
  • When provided, this is the ID of the entity whose contribution to the subscription entitlement is overridden. If the entity is not yet part of the subscription, the override takes effect when the entity is added. See entity-level entitlement overrides.
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.

Constraints

Applicable only for subscription-level entitlement overrides. i.e. Not applicable when entity_id and entity_type are set.

effective_from
optional, timestamp(UTC) in seconds

The starting date and time for the entitlement override. It indicates when the override becomes effective.

Constraints

Applicable only for subscription-level entitlement overrides. i.e. Not applicable when entity_id and entity_type are set.

is_enabled
required, boolean