List operations

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

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 parameters can be of the following types:

• String
• Enumerated string
• Number
• Timestamp
• Boolean

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

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

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

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][0]=basic&plan_id[in][1]=pro
• Enumerated string: status[in][0]=payment_due&status[in][1]=not_paid

not_in

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

• 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

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

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

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

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

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

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][0]=1499&price[between][1]=4999
• Timestamp: created_at[between][0]=1454371200&created_at[between][1]=1454371200

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

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

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

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

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.