Using cursor pagination with the Recharge API

Calling the Recharge API can return multiple 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.

Recharge's endpoints use pagination so that it is easier to manage the results of any call. Pagination splits the response result set into smaller batches and retrieves them one at a time. A user must paginate (i.e. progress) through the batches to collect all the data.

Two parameters 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.

Recharge sets a limit of 50 records per batch when fetching data through the API. You can increase the limit to a maximum of 250 records in a single batch.

---

Cursor Pagination

Cursor pagination is Recharge's preferred method of pagination. Cursor pagination is supported in all 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 returned batch also contains two additional pieces of information:

1. the previous_cursor - which is a pointer to the previous batch of results and is absent for the first batch of results
2. the next_cursor - which is a pointer to the next batch of results and absent for the last batch of results

Cursor pagination makes for more efficient queries and management of the data, unlike Page Pagination which requires every batch to go through all the prior result sets before getting the next.

Using cursor pagination

You can use cursor pagination for all API versions with a slight difference in the cursor locations:

2021-11

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. See 2021-11 cursor pagination for additional information.

2021-01

In the API's response, the Cursor values for navigating to the next and previous batches of results are combined and included in a custom header named link. With this implementation, you must parse the header to get the cursor value. See 2021-01 cursor pagination for additional information.

---

Page Pagination

🚧

Note:

Page Pagination is only available for 2021-01. Recharge recommends upgrading to Cursor Pagnination for ease of use.

Page Pagination uses a page number, similar to the page system in a book. With Page Pagination, the query must go through all the pages to get to the page it's looking for, and must do this for every batch that needs to be retrieved. This can cause inefficiencies for large result sets.

See2021-01 page pagination for additional information.

---

Resources

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

• JavaScript example
• PHP example