Using cursor pagination with the Recharge API
Making a call to the Recharge API can return a lot of results (e.g. all the
Orders created since activity started or all the
Customers in the store) which can be challenging for an application to manage as well as time and resource consuming.
At Recharge, all our endpoints use pagination to make the results of any call easier to manage. Pagination splits the response result set into smaller batches of results which are retrieved one at a time. A user must paginate (i.e. progress) through the batches to collect all the data.
There are two parameters which control the batches:
limit: the number of records allowed per batch.
type: method to organise the result batches. Two of the most common ones are
Our default limit is 25 and we allow up to 250 results.
Cursor pagination is our preferred method of pagination. Cursor pagination is supported in all our API versions. This pagination method links batches to one another using pointers to the previous and next batch of results.
In Recharge cursor based pagination, the batch returned also contains 2 additional pieces of information:
previous_cursor- which is a pointer to the previous batch of results ( absent for the first batch of results )
next_cursor- which is a pointer to the next batch of results ( absent for the last batch of results )
Cursor pagination makes for more efficient queries and management of the data. Unlike the other common type of pagination (Page Pagination) which requires for every batch to go through all the prior result sets before getting the next.
Using cursor pagination
You can use cursor pagination for all versions of the API with a slight difference in the cursor locations. See below:
Cursor values for the next and previous cursor values appear separately in the body of the JSON response as the
Related reference: 2021-11 cursor pagination
Cursor values for the next and previous batch of results are found concatenated in a custom header in the API's response. The name of this header is
The downside of this implementation is that you have to parse the header to get the cursor value, which is why we changed it for 2021-11.
Related reference: 2021-01 cursor pagination
Page Pagination is only available for 2021-01. We recommend migrating to Cursor Pagination
Page Pagination is the other common type of pagination. Instead of cursors, it uses a simple page number. Similar to the page system in a book. And just like a book, the query has to go through all the pages in order to get to the page it's looking for and this for every batch that needs to be retrieved which can cause inefficiencies on large result sets.
Related reference: 2021-01 page pagination
The following articles contain code patterns and additional explanations for handling data using cursor pagination server-side.
Updated over 1 year ago