GET /customers/{customer-id}/customer_entitlements

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:

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.