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

https://{site}.chargebee.com/api/v2/entitlement_overrides

Model Class

 

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

      This is a list of the event types we currently support. We will continue
      to add more events moving forward. All events follow a uniform pattern -
      <resource>_<event_name>. The resources that will be
      present in the event content are provided beneath each event type's
      description.
    
 
Note: If consolidated invoicing is enabled, the
      attributes invoice.subscription_id and
      credit_note.subscription_id should not be used
      (as it will not be present if the invoice / credit note has lines from
      multiple subscriptions). Instead to know the related subscriptions,
      their line_items' subscription_id attribute should be referred.
    
 
 
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
  
 
 
 
Consent Fields for Entitlement override
 
 
Custom Fields for Entitlement override
 
  

      Upsert or remove entitlement overrides for a subscription
      
 
Idempotency Supported
 
 
  Try in API Explorer
   
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
      
 

  Try in API Explorer

 
 
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" 
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 
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
 
Adding entitlement overrides for a feature
 
 
 
200:
 
OK
 
STATUS
 

    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
 
 
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.
 
 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_overrides[effective_from][0..n]
 
optional, timestamp(UTC) in seconds 
  
   
 
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
      
  
 
  Try in API Explorer
   
Retrieve the list of entitlement overrides for a subscription.
  
Notes
 
 

        Sample Request
      
 

  Try in API Explorer

 
 
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
 
 
200:
 
OK
 
STATUS
 

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