You are viewing the documentation for Chargebee API V2. If you're using the older version (V1), click here.

subscriptions inherit item_entitlements from items 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 by providing you a way to specify the entitlement_overrides component for any subscription_entitlement. Such an override, when present, becomes the effective entitlement, thereby overriding any inherited_entitlements for the subscription.

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 override [ JSON ]

{ "entity_id": "Jdf63vklssSDFdb", "entity_type": "subscription", "feature_id": "fea-be1a9281-d8df-48ce-82e2-294667eb4d94", "feature_name": "Quickbooks Integration_123", "id": "override-1935f8d6-b791-4181-9fa2-65fd8bfbd7ae", "name": "Available", "object": "entitlement_override", "value": "true" }

API Index URL GET

https://{site}.chargebee.com/api/v2/entitlement_overrides
id
string, max chars=50
Unique identifier for the entitlement override. This is always auto-generated.
entity_id
optional, string, max chars=50
The id of the subscription to which this entitlement override belongs.
entity_type
optional, string, max chars=50
The name of Chargebee resource that this entitlement override is associated with. The value is always subscription.
feature_id
optional, string, max chars=50
The id of the feature towards which this entitlement override has been granted.
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

expires_at
optional, timestamp(UTC) in seconds
The expiry date for the entitlement_override. Once expired, the entitlement_override object is no longer returned.
Sample Request
# Adding entitlement overrides for a feature
curl  https://{site}.chargebee.com/api/v2/subscriptions/Jdf63vklssSDFdb/entitlement_overrides \
     -X POST  \
     -u {site_api_key}:\
     -d action="upsert" \
     -d entitlement_overrides[feature_id][0]="fea-be1a9281-d8df-48ce-82e2-294667eb4d94" \
     -d entitlement_overrides[value][0]="true"
copy

Sample Response [ JSON ]

URL Format POST

https://{site}.chargebee.com/api/v2/subscriptions/{subscription_id}/entitlement_overrides
action
optional, enumerated string
The specific action to be performed for each entitlement_override specified. .
Possible values are
upsertIf the entitlement_override already exists for the feature_id and {subscription_id} combination, the value of the entitlement_override is updated. If it doesn’t exist, a new entitlement_override is created.removeDeletes the entitlement_override for the feature_id and item_id combination, if it exists.
+
entitlement_overrides
Parameters for entitlement_overrides. Multiple entitlement_overrides can be passed by specifying unique indices.
pass parameters as entitlement_overrides[<param name>][<idx:0..n>]
entitlement_overrides[feature_id][0..n]
required, string, max chars=50
The id of the feature towards which this entitlement override has been granted.
entitlement_overrides[value][0..n]
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.
.
entitlement_overrides[expires_at][0..n]
optional, timestamp(UTC) in seconds
The expiry date for the entitlement_override. When not passed, the entitlement_override does not expire. This must be a value in the future and is relevant only when the action is upsert. The entitlement_override object is no longer returned after this date has passed.
always returned
Resource object representing entitlement_override
Retrieve the list of entitlement overrides for a subscription.
Sample Request
curl  https://{site}.chargebee.com/api/v2/subscriptions/Jdf63vkLssSDFdb/entitlement_overrides \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=1 \
     --data-urlencode offset="0"
copy
curl  https://{site}.chargebee.com/api/v2/subscriptions/Jdf63vkLssSDFdb/entitlement_overrides \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=1 \
     --data-urlencode offset="0"

Sample Response [ JSON ]

Show more...
{"list": [ {"entitlement_override": { "entity_id": "Jdf63vkLssSDFdb", "entity_type": "subscription", "feature_id": "fea-7259be6f-43fd-4564-ae0b-d98386f38071", "feature_name": "API call limit", "id": "override-bf37fcff-c402-4811-a0b2-a675ed859b17", "name": "", "object": "entitlement_override", "value": "50" }}, {..} ]}

URL Format GET

https://{site}.chargebee.com/api/v2/subscriptions/{subscription_id}/entitlement_overrides
limit
optional, integer, default=10, min=1, max=100
The number of resources to be returned.
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
Resource object representing entitlement_override
next_offset
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”.