GET /customers/{customer-id}/customer_entitlements

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

<p><a href='list-ops#pagination'>Pagination</a> works differently for this endpoint than other List endpoints in the Billing API. In other list endpoints, the <code>limit</code> parameter sets the limit on the total number of objects returned in the response. However, in this endpoint, the <code>limit</code> parameter  defines the number of features for which the <code>customer_entitlement</code> objects are returned. For example, if <code>limit</code> = n, then all <code>customer_entitlement</code> objects for up to n features are returned.</p>

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

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

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"
            }
        }
    ]
}

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

Servers

{protocol}://{site}.{environment}:{port}/api/v2
{protocol}://{site}-test.{environment}:{port}/api/v2

Path parameters

Name	Type	Required	Description
`customer-id`	String	Yes

Request headers

Name	Type	Required	Description
`chargebee-request-origin-device`	String	No	The device from which the customer has made the request
`chargebee-business-entity-id`	String	No	If the site has multiple business entities, you can use this custom HTTP header to specify the business entity for which Chargebee should perform the operation.
`chargebee-request-origin-user`	String	No	The email address of your customer/user. Use this when the email address has only ASCII characters.
`chargebee-request-origin-ip`	String	No	The IP address of the customer where the request originated
`chargebee-request-origin-user-encoded`	String	No	The Base64-encoded email address of your customer/user. Use this if the email address has UTF-8 characters. When this header is provided, the header chargebee-request-origin-user is ignored.

Query parameters

Name Type Required Description

Name	Type	Required	Description
`limit`	Integer	No	The number of features for which to return `customer_entitlement` objects. See also Pagination for List customer entitlements. Default value: 10
`consolidate_entitlements`	Boolean	No	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. Default value: false
`offset`	String	No	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.

limit

Integer

The number of features for which to return customer_entitlement objects.

See also

Pagination for List customer entitlements.

Default value: 10

consolidate_entitlements

Boolean

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.

Default value: false

offset

String

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.

How to start integrating

Add HTTP Task to your workflow definition.
Search for the API you want to integrate with and click on the name.
- This loads the API reference documentation and prepares the Http request settings.
Click Test request to test run your request to the API and see the API's response.