# List customer entitlements

> For the complete machine-readable documentation index, see [llms.txt](https://apidocs.chargebee.com/llms.txt).


[Eventually Consistent](/docs/api/read-consistency)

**Tip**

To retrieve subscription entitlements for a specific subscription, use the [List subscription entitlements API](/docs/api/subscription_entitlements/list-subscription-entitlements).

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](/docs/api/subscriptions/subscription-object#status) of `active` or `non_renewing`.

Pagination

[Pagination](/docs/api/list-ops#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[](#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-1)

##### Feature 2[](#feature-2)

##### Feature 3[](#feature-3)

##### Subscriptions[](#subscriptions)

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

##### Subscription entitlements[](#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-responses)

API calls to this endpoint work as follows:

###### First call[](#first-call)

Consider the first call with `limit` set to `2`.

###### Response[](#response)

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[](#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.

###### Response[](#response)

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

#### cURL

```bash
curl  https://{site}.chargebee.com/api/v2/customers/cus01/customer_entitlements \
     -u {site_api_key}:
```

#### .NET

```dotnet
using ChargeBee.Api;
using ChargeBee.Models;

ApiConfig.Configure("{site}","{site_api_key}");
ListResult result = CustomerEntitlement.EntitlementsForCustomer("cus01").Request();

foreach (var listItem in result.List){
  CustomerEntitlement customerEntitlement = listItem.CustomerEntitlement;
}
```

#### Go

```go
package main
import (
    "fmt"
    "github.com/chargebee/chargebee-go/v3"
    customerentitlementAction "github.com/chargebee/chargebee-go/v3/actions/customerentitlement"
)
func main() {
    chargebee.Configure("{site_api_key}","{site}");
    res,err := customerentitlementAction.EntitlementsForCustomer("cus01", nil).ListRequest()
    if err != nil {
        fmt.Println(err)
    } else {
        for idx := 0; idx < len(res.List); idx++ {
            CustomerEntitlement := res.List[idx].CustomerEntitlement
        }
    }
}
```

#### Go

```go
package main

import (
  "fmt"
  "github.com/chargebee/chargebee-go/v4"
)

func main() {
  config := &chargebee.ClientConfig{
    SiteName: "{site}",
    ApiKey: "{site_api_key}",
  }    
  client := chargebee.NewClient(config)
  req := &chargebee.CustomerEntitlementEntitlementsForCustomerRequest{}
  res, err := client.CustomerEntitlement.EntitlementsForCustomer("cus01", req)
      if err != nil {
        fmt.Println(err)
    } else {
        for idx := 0; idx < len(res.List); idx++ {
            CustomerEntitlement := res.List[idx].CustomerEntitlement
        }
    }
}
```

#### Java

```java
import com.chargebee.*;
import com.chargebee.ListResult;
import com.chargebee.models.*;
import com.chargebee.models.enums.*;
import java.io.IOException;
import java.util.List;

public class Sample {

    public static void main(String args[]) throws IOException, Exception {
        Environment.configure("{site}", "{site_api_key}");
        ListResult result = CustomerEntitlement.entitlementsForCustomer("cus01").request();

        for (ListResult.Entry entry : result) {
            CustomerEntitlement customerEntitlement = entry.customerEntitlement();
        }
    }
}
```

#### Java

```java
import com.chargebee.v4.client.ChargebeeClient;
import com.chargebee.v4.models.customerEntitlement.CustomerEntitlement;
import com.chargebee.v4.models.customerEntitlement.params.CustomerEntitlementEntitlementsForCustomerParams;
import com.chargebee.v4.models.customerEntitlement.responses.CustomerEntitlementEntitlementsForCustomerResponse;
import java.util.List;

public class CustomerEntitlementEntitlementsForCustomer {

    public static void main(String[] args) {
        ChargebeeClient client = ChargebeeClient.builder()
            .apiKey("{site_api_key}")
            .siteName("{site}")
            .build();

        CustomerEntitlementEntitlementsForCustomerResponse response = client.customerEntitlements().entitlementsForCustomer("cus01");
    }
}
```

#### Node.js

```node
import Chargebee from "chargebee";

const chargebee = new Chargebee({
    site: "{site}",
    apiKey: "{site_api_key}",
});

try {
    const result = await chargebee.customerEntitlement.entitlementsForCustomer("cus01");
    result.list.forEach((entry) => {
        console.log(entry);
        const customerEntitlement = entry.customer_entitlement;
    });
} catch (err) {
    console.log(err);
}
```

#### PHP

```php
<?php

require __DIR__ . '/vendor/autoload.php';

use Chargebee\ChargebeeClient;

$chargebee = new ChargebeeClient(options: [
    "site" => "{site}",
    "apiKey" => "{site_api_key}",
]);
$result = $chargebee->customerEntitlement()->entitlementsForCustomer("cus01");
foreach($result->list as $entry) {
    $customerEntitlement = $entry->customer_entitlement;
}
```

#### Python

```python
from chargebee import Chargebee, Filters

cb_client = Chargebee(api_key="{site_api_key}", site="{site}")
entries = cb_client.CustomerEntitlement.entitlements_for_customer("cus01")
for entry in entries.list:
    customer_entitlement = entry.customer_entitlement
```

#### Ruby

```ruby
require 'chargebee'

ChargeBee.configure(:site => "{site}",
  :api_key => "{site_api_key}")

list = ChargeBee::CustomerEntitlement.entitlements_for_customer("cus01")

list.each do |entry|
  customer_entitlement = entry.customer_entitlement
end
```

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

## 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](/docs/api/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.

- `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](/docs/api/subscription_entitlements) , based on the feature type.

## Returns

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

- `customer_entitlement` (Customer entitlement object)
  Resource object representing `customer_entitlement`