# List operations

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


Chargebee provides "List" APIs for the bulk fetching of resources. By default, the resource list is sorted in ascending order by the `created_at` attribute. List APIs can be found for most resources. Examples include:

-   List customers
-   List subscriptions

## Data freshness[](#data-freshness)

List operations are eventually consistent, so a list response might not reflect a recent write. To read your own writes, call the resource's retrieve endpoint instead. For more information, see [Read consistency](/docs/api/read-consistency).

## Pagination

Since the number of resources can be very large, the API paginates the response by returning only 10 resources by default. The response from a single call to a list API is called a page. Further calls must be made to the API to retrieve more pages.

Pagination is controlled using the following parameters:

-   `limit`: Specifies the number of resources to be included in the page. The value ranges from `1` to `100`, inclusive; and defaults to `10`.
-   `offset`: This parameter specifies-in the sorted list of resources-the position from where the page returned should start. When calling a list API, the presence of the `next_offset` attribute in the response indicates that more resources are available. To retrieve the next page of resources, set the `offset` parameter to the value of `next_offset` returned in your previous call. When `offset` is not provided, the first page of resources is returned.

## Sorting

In the List endpoints, the `sort_by` parameter is provided for sorting the result in the desired order. Both the attribute (such as created\_at or updated\_at) based on which the result should be sorted, and the order of sorting (ascending or descending) can be specified.

**Example:** Sort by `created_at` attribute in the ascending (earliest first) order.

## Filtering

While using List endpoints, you can filter the resources returned based on the values of certain attributes. Each filter parameter specifies a single attribute, an operator, and a value.

The specific attributes supported and the operators available for filtering vary from resource to resource. The filter parameters available for a List endpoint can be found under the "Filter Params" section in its documentation.

### Filter types[](#filter-types)

Filter parameters can be of the following types:

-   String
-   Enumerated string
-   Number
-   Timestamp
-   Boolean

### Applying multiple filters[](#applying-multiple-filters)

When you apply multiple filter parameters, their effects add up. In other words, the API returns the intersection of the filtered sets of resources.

### Filtering by custom fields[](#filtering-by-custom-fields)

You can also filter List API results by [custom fields](/docs/api/advanced-features#filtering-by-custom-field-values). This feature is turned off by default. To turn it on, contact [Chargebee Support](https://www.chargebee.com/docs/billing/2.0/kb/getting-started/how-to-contact-chargebees-support-team?utm_source=docs_api&utm_medium=content&utm_campaign=support).

### Filter operators[](#filter-operators)

This section describes all the filter operators available in the API, the filter types that support them, and some examples of their usage.

#### **is**[](#is)

Returns resources where the value of the attribute matches the value of the filter.

**Supported filter types:** String, enumerated string, number, boolean

**Examples:**

-   String: `email[is]=john@acme.com`
-   Enumerated string: `status[is]=paid`
-   Number: `price[is]=1499`
-   Boolean: `taxable[is]=true`

#### **is\_not**[](#isnot)

Returns resources where the value of the attribute does not match the value of the filter.

**Supported filter types:** String, enumerated string, number

**Examples:**

-   String: `plan_id[is_not]=basic`
-   Enumerated string: `status[is_not]=paid`
-   Number: `amount_unused[is_not]=0`

#### **in**[](#in)

Returns resources where the value of the attribute matches any of the specified values of the filter.

**Supported filter types:** String, enumerated string

**Examples:**

-   String: `plan_id[in]=["basic", "pro"]`
-   Enumerated string: `status[in]=["payment_due", "not_paid"]`

#### **not\_in**[](#notin)

Returns resources where the value of the attribute does not match any of the specified values of the filter.

**Supported filter types:** String, enumerated string

#### **is\_present**[](#ispresent)

-   When the filter value is `true`: returns resources where the value of the attribute is set (the value is not null).
-   When the filter value is `false`: returns resources where the value of the attribute is not set (the value is null).

**Supported filter types:** String, enumerated string, number, timestamp, boolean

**Example:** `email[is_present]=false` (returns customer resources whose email attribute is not set)

#### **starts\_with**[](#startswith)

Returns resources where the value of the attribute starts with the value of the filter.

**Supported filter type:** String

**Example:** `company[starts_with]=A`

#### **gt**[](#gt)

Returns resources where the value of the attribute is greater than the value of the filter.

**Supported filter type:** Number

**Example:** `price[gt]=1000`

#### **gte**[](#gte)

Returns resources where the value of the attribute is greater than or equal to the value of the filter.

**Supported filter type:** Number

**Example:** `price[gte]=1499`

#### **lt**[](#lt)

Returns resources where the value of the attribute is less than the value of the filter.

**Supported filter type:** Number

**Example:** `price[lt]=1000`

#### **lte**[](#lte)

Returns resources where the value of the attribute is less than or equal to the value of the filter.

**Supported filter type:** Number

**Example:** `price[lte]=1499`

#### **between**[](#between)

Returns resources where the value of the attribute is within the inclusive range specified by the two values of the filter.

**Supported filter types:** Number, timestamp

**Examples:**

-   Number: `price[between]=[1499, 4999]`
-   Timestamp: `created_at[between]=[1454371200, 1454371200]`

#### **on**[](#on)

Returns resources where the date in the value of the attribute matches the date specified in the value of the filter.

**Supported filter type:** Timestamp

**Example:** `created_at[on]=1456147530`

Since the Unix timestamp `1456147530` is the same as 2016-02-22 13:25:30 UTC, the resources created on the date 2016-02-22 UTC are returned.

#### **before**[](#before)

Returns resources where the value of the timestamp attribute is less than the value of the filter.

**Supported filter type:** Timestamp

**Example:** `created_at[before]=1456147530`

#### **after**[](#after)

Returns resources where the value of the timestamp attribute is greater than the value of the filter.

**Supported filter type:** Timestamp

**Example:** `created_at[after]=1456147530`

## Fetching deleted resources

Normally when you fetch resources using our List APIs the deleted resources will not be included. However, if you specify the `include_deleted` param as `true`, the deleted resources will also be included as part of the response. The `deleted` attribute can be used to identify the deleted resources in the response.

## Incremental syncing of resources

For purposes such as data warehousing, you may need to sync data periodically from Chargebee. We recommend using the **list API**s for the various resources you want to sync. (For example, List customers or List subscriptions.) Use the `updated_at` filter and the `sort_by` parameter set to `updated_at asc` when calling the API. Given below is a more detailed algorithm:

### Initial Sync[](#initial-sync)

1.  Initialize `end_time` = sync start time.
2.  Call the **list API** with the following parameters (the returned data will be paginated, so do this till the page size is 0):
    -   `updated_at` set to `before end_time`.
    -   `sort_by` set to `updated_at asc`.
    -   offset set to the value of `next_offset` from the previous API call.
3.  For every resource fetched above: If the `resource_version` of received resource is greater than (>) `resource_version` of same resource cached or stored on your side, update the resource on your side with the received version. If the condition is not true, then ignore the received resource.

### All Subsequent Syncs[](#all-subsequent-syncs)

1.  Initialize `last_sync_time` = previously stored `end_time` minus 5 minutes. (During the previous sync, updates may have happened concurrently while the resources were being fetched. The negative 5 minutes is to ensure that any such resources missed during the last sync, are fetched this time.)
2.  Set `end_time` = current time.
3.  Call the **list API** with the following parameters (the returned data will be paginated, so do this till the page size is 0):
    -   `updated_at` set to `after last_sync_time`.
    -   `updated_at` set to `before end_time`.
    -   `sort_by` param set to `updated_at asc`.
    -   `offset` set to the value of `next_offset` from the previous API call.
4.  For every resource fetched above: If the `resource_version` of received resource > `resource_version` of same resource cached or stored on your side, update the resource on your side with the received version. If the condition is not true, then ignore the received resource.

**Note:** If you need to be notified of events immediately, use [webhooks](https://www.chargebee.com/docs/webhook_settings.html). This is useful for instance, when you must provision services as soon as a subscription has been created.