Settings
API Version
Product Catalog
Library

Customer entitlements

The customer_entitlement resource can be viewed as a subset of the subscription_entitlement resource enhanced with the customer’s ID. It is introduced to help retrieve all subscription entitlements for a specific customer.

Sample customer entitlement [ JSON ]

{ "customer_entitlement": { "customer_id": "cus01", "subscription_id": "sub123", "feature_id": "licenses", "value": "60", "name": "60 licenses", "is_enabled": true, "object": "customer_entitlement" } }

API Index URL GET

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

Model Class

 

      Customer entitlement attributes
      
 
customer_id
 

      string, max chars=50
 The unique identifier of the customer to which this entitlement belongs. 
 
 
subscription_id
 

      optional, string, max chars=50
 The unique identifier of the subscription to which this entitlement belongs. 
 
 
feature_id
 

      optional, string, max chars=50
 The unique identifier of the feature towards which this subscription entitlement has been granted. 
 
 
value
 

      optional, string, max chars=50
 The value denoting the effective entitlement level that the subscription has towards the feature. 
 
 
name
 

      optional, string, max chars=50
 
The display name for the entitlement level. The value is automatically generated based on feature.type:
 
     
  • When feature.type is range or quantity: the name is the space-separated concatenation of value and the pluralized form of feature.unit. For example, if value is 20 and feature.unit is user, then name becomes 20 users.
    •  
  • When feature.type is custom, the name is the same as value.
    •  
  • When feature.type is switch: name is set to Available when value is true; it's set to Not Available when value is false.
    •  
 
 
 
is_enabled
 

      boolean
 When true, indicates that the subscription_entitlement is enabled. 
 See also: Enable/disable subscription entitlement. 
 
 
 
 
 
customer_id customer_id
 

          string, max chars=50
 The unique identifier of the customer to which this entitlement belongs. 
 
subscription_id subscription_id
 

          optional, string, max chars=50
 The unique identifier of the subscription to which this entitlement belongs. 
 
feature_id feature_id
 

          optional, string, max chars=50
 The unique identifier of the feature towards which this subscription entitlement has been granted. 
 
value value
 

          optional, string, max chars=50
 The value denoting the effective entitlement level that the subscription has towards the feature. 
 
name name
 

          optional, string, max chars=50
 
The display name for the entitlement level. The value is automatically generated based on feature.type:
 
     
  • When feature.type is range or quantity: the name is the space-separated concatenation of value and the pluralized form of feature.unit. For example, if value is 20 and feature.unit is user, then name becomes 20 users.
    •  
  • When feature.type is custom, the name is the same as value.
    •  
  • When feature.type is switch: name is set to Available when value is true; it's set to Not Available when value is false.
    •  
 
 
is_enabled is_enabled
 

          boolean
 When true, indicates that the subscription_entitlement is enabled. 
 See also: Enable/disable subscription entitlement. 
 
 
 
 
Consent Fields for Customer entitlement
 
 
Custom Fields for Customer entitlement
 
  

      List customer entitlements
      
  
 

    Disabled by default
    
This endpoint is disabled by default. To enable it, contact Chargebee Support.




Retrieves a list of all customer_entitlement objects for the specified customer.



    Tip
    
To retrieve subscription entitlements for a specific subscription, use the List subscription entitlements API.








    
Pagination works differently for this endpoint than other List endpoints in the Billing API. In other list endpoints, the limit parameter sets the limit on the total number of objects returned in the response. However, in this endpoint, the limit parameter  defines the number of features for which the customer_entitlement objects are returned. For example, if limit = n, then all customer_entitlement objects for up to n features are returned.



Let's look at an example:



Features



Consider the following three features defined in Chargebee for a project management software:



    
    
  • User Licenses
    • 
    
  • Support Level
    • 
    
  • Xero Integration
    • 




The feature objects are listed below:



Feature 1




{
    "feature": {
        "id": "user-licenses",
        "name": "User Licenses",
        "description": "Maximum number of user licenses allowed.",
        "status": "active",
        "type": "quantity",
        "unit": "licence",
        "levels": [
            {
                "name": "3 licences",
                "value": "3",
                "is_unlimited": false,
                "level": 1
            },
            {
                "name": "10 licences",
                "value": "10",
                "is_unlimited": false,
                "level": 2
            },
            {
                "name": "25 licences",
                "value": "25",
                "is_unlimited": false,
                "level": 3
            },
            {
                "name": "Unlimited licence",
                "value": "Unlimited",
                "is_unlimited": true,
                "level": 4
            }
        ],
        "object": "feature"
    }
}





Feature 2



{
    "feature": {
        "id": "support-level",
        "name": "Support Level",
        "description": "Level of support offered.",
        "status": "active",
        "type": "custom",
        "levels": [
            {
                "name": "Email",
                "value": "Email",
                "is_unlimited": false,
                "level": 1
            },
            {
                "name": "Chat",
                "value": "Chat",
                "is_unlimited": false,
                "level": 2
            },
            {
                "name": "Calls",
                "value": "Calls",
                "is_unlimited": false,
                "level": 3
            }
        ],
        "object": "feature"
    }
}





Feature 3



{
    "feature": {
        "id": "xero-integration",
        "name": "Xero Integration",
        "description": "Integrate your Chargebee site with Xero",
        "status": "active",
        "type": "switch",
        "object": "feature"
    }
}





Subscriptions

    
Now consider that a customer c1 has two subscriptions: s1 and s2.



Subscription entitlements

    
Consider the following subscription entitlements for s1 and s2:



    
    

        Subscription id
        Feature Name
        Entitlement Value
    

    
    
    

        s1
        User Licenses
        3
    

    

        s1
        Support Level
        Email
    

    

        s2
        User Licenses
        10
    

    

        s2
        Support Level
        Chat
    

    

        s2
        Xero Integration
        true
    

    




API responses


API calls to this endpoint work as follows:



First call

    
Consider the first call with limit set to 2.



GET /api/v2/customers/c1/customer_entitlements?limit=2




Response



{
    "list": [
        {
            "customer_entitlement": {
                "customer_id": "c1",
                "subscription_id": "s1",
                "feature_id": "user-licenses",
                "value": "3",
                "name": "3 licences",
                "is_enabled": true,
                "object": "customer_entitlement"
            }
        },
        {
            "customer_entitlement": {
                "customer_id": "c1",
                "subscription_id": "s2",
                "feature_id": "xero-integration",
                "value": "true",
                "name": "Available",
                "is_enabled": true,
                "object": "customer_entitlement"
            }
        },
        {
            "customer_entitlement": {
                "customer_id": "c1",
                "subscription_id": "s2",
                "feature_id": "user-licenses",
                "value": "10",
                "name": "10 licences",
                "is_enabled": true,
                "object": "customer_entitlement"
            }
        }
    ],
    "next_offset": "2"
}



    
Since limit = 2, the API returns the customer_entitlement for two features: User Licenses and Xero Integration. Three objects are returned, corresponding to rows 1, 3, and 5 in the table above.



Second call

    
We now retrieve the next page of the list in the second call by setting offset to the value of next_offset obtained from the previous response.



    GET /api/v2/customers/c1/customer_entitlements?limit=2&offset=2




Response



{
    "list": [
        {
            "customer_entitlement": {
                "customer_id": "c1",
                "subscription_id": "s1",
                "feature_id": "support-level",
                "value": "Email",
                "name": "Email",
                "is_enabled": true,
                "object": "customer_entitlement"
            }
        },
        {
            "customer_entitlement": {
                "customer_id": "c1",
                "subscription_id": "s2",
                "feature_id": "support-level",
                "value": "Chat",
                "name": "Chat",
                "is_enabled": true,
                "object": "customer_entitlement"
            }
        }
    ]
}



    
Although limit = 2, the customer_entitlement objects for only one more feature, namely, Support Level are returned because the remaining were covered in the previous page.  No more customer_entitlement objects remain for the customer, as indicated by the absence of the next_offset attribute in the response. The returned objects in this last call correspond to rows 2 and 4 in the table above. 



  
Notes
 
 

        Sample Request
      
 

  Try in API Explorer

 
 
curl  https://{site}.chargebee.com/api/v2/customers/cus01/customer_entitlements \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=10
 

      copy
      
Click to Copy
 
List customer entitlements for a customer
 
 
 

    Sample Response [ JSON ]
 
Show more...
 
{
    "list": [
        {
            "customer_entitlement": {
                "customer_id": "cus01",
                "subscription_id": "sub123",
                "feature_id": "licenses",
                "value": "60",
                "name": "60 licenses",
                "is_enabled": true,
                "object": "customer_entitlement"
            }
        },
        {..}
    ]
}
 

      URL Format
      GET
 

      https://{site}.chargebee.com/api/v2/customers/{customer-id}/customer_entitlements
    
 
Method
 
 
Input Parameters
 
limit[]
 

      optional, integer, default=10, min=1, max=100 
 The number of features for which to return customer_entitlement objects. 
 See also 
Pagination for List customer entitlements.
 
 
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
 
customer_entitlement  customer_entitlement
 

      always returned 
 Resource object representing customer_entitlement
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/customer_entitlements/123x