Pagination
Efficiently retrieve large datasets using offset-based or cursor-based pagination strategies.
Copy linkOverview
Pagination allows you to efficiently retrieve large sets of data from the Paystack API. Instead of returning all results at once, which could be slow and resource intensive, pagination breaks the sets of data into smaller chunks before sending them. This approach improves performance, reduces network load, and enhances the overall user experience when working with large datasets.
Copy linkPagination types
The Paystack API supports two types of pagination:
- Offset Pagination — Request specific pages using page and perPage parameters
- Cursor Pagination — Use unique identifiers (cursors) to navigate large datasets
Each type has its own use cases and implementation details.
Copy linkOffset pagination
Offset pagination allows you to request specific page and perPage values when fetching records. The page parameter specifies which page of records to retrieve, while the perPage parameter specifies how many records you want to retrieve per page.
To use offset pagination, include the page and perPage parameters as query parameters in your API request:
| Parameter | Type | Description |
|---|---|---|
| page | Number | The page to retrieve. |
| perPage | Number | The number of records to return per request. Default: 50 |
Example request:
GET /transaction?page=1&perPage=50
Info: The
metaobject in the JSON response fromGET /transactionincludes atotal_volumeparameter, which is the sum of all the transactions that have been fetched.
Copy linkCursor pagination
Cursor pagination uses a unique identifier called a cursor to keep track of where in the dataset to continue from. This method is more efficient for retrieving large datasets and provides more consistent results when items are being added or removed frequently.
To use cursor pagination, include the use_cursor query parameter and set it to true on your first fetch request. The meta object in the JSON response will contain parameters called next and previous that contain the cursors for the next and previous sets of records.
| Parameter | Type | Description |
|---|---|---|
| use_cursor | Boolean | Set this to true to retrieve results using cursor pagination. |
| next | String | A cursor to use in pagination. next points to the next page of the dataset. Set this to the next cursor received in the meta object of a previous request. |
| previous | String | A cursor to use in pagination. previous points to the previous page of the dataset. Set this to the previous cursor received in the meta object of a previous request. |
| perPage | Number | The number of records to return per request. Default: 50 |
Example request:
GET /transaction?use_cursor=true&perPage=50
Warning: Cursor-based pagination is currently only available on the following endpoints:
- Transactions
- Customers
- Dedicated Accounts
- Transfer Recipients
- Transfers
- Disputes
Copy linkBest practices
- Choose the right pagination type: Use offset-based pagination for smaller, static datasets. For larger or frequently updated datasets, prefer cursor-based pagination.
- Set reasonable page sizes: Start with the default of 50 items per page. Adjust based on your specific needs, but avoid requesting more than 1,000 items at once to prevent performance issues.
- Handle edge cases: Always check if there are more pages available. For offset-based pagination, it's best to fetch pages until no results are returned. For cursor-based pagination, the absence of a
nextcursor indicates you've reached the end. - Implement error handling: Be prepared to handle pagination-related errors, such as invalid page numbers or cursors.
- Consider rate limits: Be mindful of Paystack's rate limits when implementing pagination, especially if you're fetching large amounts of data. Implement appropriate delays between requests if necessary.
- Cache wisely: If you're caching paginated results, ensure your cache invalidation strategy accounts for potential changes in the dataset.