Pagination

A response with multiple items uses cursor-based pagination to provide efficient and scalable data retrieval. This documentation explains how to use cursor-based pagination to fetch data from the API.

What is cursor-based pagination?

Cursor-based pagination involves returning a set of data with a unique identifier, known as a “cursor”. The cursor represents a specific point in the dataset, and subsequent requests can be made by providing the cursor as a query parameter. This approach enables clients to efficiently retrieve large datasets without having to fetch all records at once.

Fetching data with cursor-based pagination

To fetch data using cursor-based pagination, follow these steps:

1. Start by requesting the first page of data without the cursor set. If you don’t provide a limit, the API will return 50 records.
2. The response will contain an array of records and a next_cursor field, which represents the next set of data.
3. If no more records exist (i.e., next_cursor is null), stop fetching data.
4. To fetch the next page of data, provide the cursor value from the previous response as a query parameter.

Paginated request fields

Paginated response fields

Retrieving the first cursor

Here’s an example request and response format for an API endpoint when we start listing data:

1
GET /orders?limit=2

1
{
2
  "data": [
3
    {
4
      "id": "1633754596890-82bd44bb-ac03-428f-803f-bbffea92397c",
5
      "gross_amount": {
6
        "amount": 11500,
7
        "currency": "ZAR"
8
      }
9
    },
10
    {
11
      "id": "1633754596890-0664eb40-a2d3-4095-bdc8-fa8267376bc3",
12
      "gross_amount": {
13
        "amount": 20700,
14
        "currency": "ZAR"
15
      }
16
    }
17
  ],
18
  "next_cursor": "MTczOTM3MDQwODg3NC0zNDJlMzlkMC1lMzY1LTQ2ZDAtYWZiMC1hODYxNTU5Mjg1ZGI="
19
}

Retrieving the next pages

1
GET /orders?limit=2&cursor=MTczOTM3MDQwODg3NC0zNDJlMzlkMC1lMzY1LTQ2ZDAtYWZiMC1hODYxNTU5Mjg1ZGI%3D

Until, eventually, the next_cursor field is null

1
{
2
  "data": [
3
    {
4
      "id": "1738754596890-29704755-1719-466c-8c4d-fe999e7b6c3a",
5
      "gross_amount": {
6
        "amount": 46850,
7
        "currency": "ZAR"
8
      }
9
    },
10
    {
11
      "id": "1738754596890-6ed8ba62-4a79-41c5-81b5-156723d7fec3",
12
      "gross_amount": {
13
        "amount": 38106,
14
        "currency": "ZAR"
15
      }
16
    }
17
  ],
18
  "next_cursor": null
19
}