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:
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.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[asc] = "created_at". Sorts by created_at attribute in the ascending (earliest first) order.
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:
Note
When multiple filter parameters are applied, their effects add up. In other words, the API returns the intersection of the filtered sets of resources.
This section describes all the filter operators available in the API, the filter types that support them, and some examples of their usage.
Returns resources where the value of the attribute matches the value of the filter.
email[is] = "john@acme.com"
status[is] = "paid"
price[is] = "1499"
taxable[is] = "true"
Returns resources where the value of the attribute does not match the value of the filter.
plan_id[is_not] = "basic"
status[is_not] = "paid"
amount_unused[is_not] = "0"
Returns resources where the value of the attribute matches any of the specified values of the filter.
plan_id[in] = "[basic,pro]"
status[in] = "[payment_due,not_paid]"
Returns resources where the value of the attribute does not match any of the specified values of the filter.
plan_id[not_in] = "[basic,pro]"
status[not_in] = "[payment_due,not_paid]"
true
: returns resources where the value of the attribute is set (the value is not null).false
: returns resources where the value of the attribute is not set (the value is null).String: email[is_present] = "false"
(This returns customer resources whose email attribute is not set.)
Returns resources where the value of the attribute starts with the value of the filter.
company[starts_with] = "A"
Returns resources where the value of the attribute is greater than the value of the filter.
price[gt] = "1000"
Returns resources where the value of the attribute is greater than or equal to the value of the filter.
price[gte] = "1499"
Returns resources where the value of the attribute is less than the value of the filter.
price[lt] = "1000"
Returns resources where the value of the attribute is less than or equal to the value of the filter.
price[lte] = "1499"
Returns resources where the value of the attribute is within the inclusive range specified by the two values of the filter.
price[between] = "[1499,4999]"
created_at[between] = "[1454371200,1454371200]"
Returns resources where the date in the value of the attribute matches the date specified in the value of the filter.
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.
Returns resources where the value of the timestamp attribute is less than the value of the filter.
created_at[before] = "1456147530"
Returns resources where the value of the timestamp attribute is greater than the value of the filter.
created_at[after] = "1456147530"
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:
end_time
= sync start time.updated_at
set to before
end_time
.sort_by
set to updated_at
asc
.next_offset
from the previous API call.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.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.)end_time
= current time.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.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.