Settings
API Version
Product Catalog
Library

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

ChargeBee::EntitlementOverride

Entitlement override attributes

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.
  • 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. Once expired, the entitlement_override object is no longer returned.
effective_from
optional, timestamp(UTC) in seconds
This field represents the starting date and time for the entitlement override. It indicates when the override becomes effective.
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.
  • 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 expires_at
optional, timestamp(UTC) in seconds
The expiry date for the entitlement_override. Once expired, the entitlement_override object is no longer returned.
effective_from effective_from
optional, timestamp(UTC) in seconds
This field represents the starting date and time for the entitlement override. It indicates when the override becomes effective.

Consent Fields for Entitlement override

Custom Fields for Entitlement override

Upsert or remove entitlement overrides for a subscription

Idempotency Supported
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 Codes 
 
require 'chargebee'
ChargeBee.configure(:site => "{site}",
  :api_key => "{site_api_key}")
result = ChargeBee::EntitlementOverride.add_entitlement_override_for_subscription("Jdf63vklssSDFdb",{
  :action => "UPSERT",
  :entitlement_overrides => [
    {
      :feature_id => "fea-be1a9281-d8df-48ce-82e2-294667eb4d94",
      :value => "true"
    }]
  })
entitlement_override = result.entitlement_override

 
require 'chargebee'
ChargeBee.configure(:site => "{site}",
  :api_key => "{site_api_key}")
result = ChargeBee::EntitlementOverride.add_entitlement_override_for_subscription("Jdf63vklssSDFdb",{
  :action => "UPSERT",
  :entitlement_overrides => [
    {
      :feature_id => "fea-be1a9281-d8df-48ce-82e2-294667eb4d94",
      :value => "true",
      :expires_at => 1649243933
    }]
  })
entitlement_override = result.entitlement_override

 
require 'chargebee'
ChargeBee.configure(:site => "{site}",
  :api_key => "{site_api_key}")
result = ChargeBee::EntitlementOverride.add_entitlement_override_for_subscription("Jdf63vkLssSDFdb",{
  :action => "REMOVE",
  :entitlement_overrides => [
    {
      :feature_id => "fea-49bdaffa-1a71-429c-b2f7-5be5f89a37eb"
    }]
  })
entitlement_override = result.entitlement_override
copy
Click to Copy
Adding entitlement overrides for a feature
 
require 'chargebee'
ChargeBee.configure(:site => "{site}",
  :api_key => "{site_api_key}")
result = ChargeBee::EntitlementOverride.add_entitlement_override_for_subscription("Jdf63vklssSDFdb",{
  :action => "UPSERT",
  :entitlement_overrides => [
    {
      :feature_id => "fea-be1a9281-d8df-48ce-82e2-294667eb4d94",
      :value => "true"
    }]
  })
entitlement_override = result.entitlement_override

Sample Result [ 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

ChargeBee::EntitlementOverride.add_entitlement_override_for_subscription(<subscription_id>,{<param name> => <value>,<param name> => <value> ...})

Input Parameters

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.
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[+]
feature_id
required, string, max chars=50
The id 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.
expires_at
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.
effective_from
optional, timestamp(UTC) in seconds
This field represents the starting date and time for the entitlement override. It indicates when the override becomes effective.

Returns

entitlement_override entitlement_override
always returned
Resource object representing entitlement_override

Sample admin console URL

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

List entitlement overrides for a subscription

Retrieve the list of entitlement overrides for a subscription.

Notes

Sample Codes 
 
require 'chargebee'
ChargeBee.configure(:site => "{site}",
  :api_key => "{site_api_key}")
    list = ChargeBee::EntitlementOverride.list_entitlement_override_for_subscription("Jdf63vkLssSDFdb")
  :limit => 1,
  :offset => "0"
  })
list.each do |entry|
  entitlement_override = entry.entitlement_override
end
copy
Click to Copy
 
require 'chargebee'
ChargeBee.configure(:site => "{site}",
  :api_key => "{site_api_key}")
    list = ChargeBee::EntitlementOverride.list_entitlement_override_for_subscription("Jdf63vkLssSDFdb")
  :limit => 1,
  :offset => "0"
  })
list.each do |entry|
  entitlement_override = entry.entitlement_override
end

Sample Result [ 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

ChargeBee::EntitlementOverride.list_entitlement_override_for_subscription(<subscription_id>,{<param name> => <value>,<param name> => <value> ...})

Input Parameters

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.

Returns

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