API Version
Product Catalog
Library

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 directly set the value for any subscription_entitlement.

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 ]

{ "entitlement_override": { "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

Model Class

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.
id id
string, max chars=50
Unique identifier for the entitlement override. This is always auto-generated.
entity_id entity_id
optional, string, max chars=50
The id of the subscription to which this entitlement override belongs.
entity_type 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 feature_id
optional, string, max chars=50
The id of the feature towards which this entitlement override has been granted.
feature_name feature_name
optional, string, max chars=50
The name of the feature towards which this entitlement override has been granted.
value 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 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 expires_at
optional, timestamp(UTC) in seconds
The expiry date for the entitlement_override. Once expired, the entitlement_override object is no longer returned.
Upserts or removes a set of entitlement_overrides for a subscription depending on the action specified. The API returns the upserted or deleted entitlement_overrides after successfully completing the operation. The operation returns an error when the first entitlement_override fails to be processed. Either all the entitlement_overrides provided in the request are processed or none.

Notes

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" 
# 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" \
     -d entitlement_overrides[expires_at][0]="1649243933" 
# Removing entitlement overrides from a subscription
curl  https://{site}.chargebee.com/api/v2/subscriptions/Jdf63vkLssSDFdb/entitlement_overrides \
     -X POST  \
     -u {site_api_key}:\
     -d action="REMOVE" \
     -d entitlement_overrides[feature_id][0]="fea-49bdaffa-1a71-429c-b2f7-5be5f89a37eb" 
copy
Click to Copy

Sample Response [ JSON ]

Show more...
{
    "list": [
        {
            "entitlement_override": {
                "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"
            }
        },
        {..}
    ]
}

URL Format POST

https://{site}.chargebee.com/api/v2/subscriptions/{subscription-id}/entitlement_overrides

Method

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.
Show all values[+]
entitlement_overrides[feature_id][0..n]
required, string, max chars=50
entitlement_overrides[value][0..n]
optional, string, max chars=50
entitlement_overrides[expires_at][0..n]
optional, timestamp(UTC) in seconds
entitlement_override entitlement_override
always returned
Resource object representing entitlement_override

Sample admin console URL

https://{site}.chargebee.com/admin-console/entitlement_overrides/123x
Retrieve the list of entitlement overrides for a subscription.

Notes

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
Click to Copy

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

Method

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.
entitlement_override entitlement_override
always returned
Resource object representing entitlement_override
next_offset 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`.

Sample admin console URL

https://{site}.chargebee.com/admin-console/entitlement_overrides/123x