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 organize the result batches. Two of the most common ones are Cursor and Page.



Our default limit is 50 and we allow up to 250 results.

Cursor Pagination

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:

  1. the previous_cursor - which is a pointer to the previous batch of results ( absent for the first batch of results )
  2. the 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 previous_cursor and next_cursor keys.

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



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

Further examples

The following articles contain code patterns and additional explanations for handling data using cursor pagination server-side.

Need Help? Contact Us