Customer entitlements

API Version

Product Catalog

Library

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

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

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.

Try in API Explorer

Disabled by default

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

Tip

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

Returns a list of customer_entitlement objects for the specified customer. The entitlements returned are for active subscriptions only. Specifically, these are subscriptions with a status of active or non_renewing.

Pagination

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.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

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

200:

STATUS

Sample Response [ JSON ]

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

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.

consolidate_entitlements[]

optional, boolean, default=false
When set to true, the response returns a unified view of entitlement values for each feature across the customer. This includes entitlements assigned directly to the customer as well as those inherited from any of the customer's subscriptions. In this mode, the subscription_id field is omitted from the response objects. The consolidated entitlement value is derived using the same logic described in the Subscription Entitlements documentation, based on the feature type.

customer_entitlement

always returned
Resource object representing customer_entitlement

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 customer entitlement [ JSON ]

API Index URL

Model Class

Customer entitlement attributes

Consent Fields for Customer entitlement

Custom Fields for Customer entitlement

List customer entitlements ¶

Sample Response [ JSON ]

URL Format GET

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL