API

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.

3If 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

FieldTypeDescription
limitintThe number of records to return per page. (default: 50)
cursorstrThe cursor used to select the next set of data.

Paginated response fields

FieldTypeDescription
dataarrayAn array of records. Each record’s data is defined in the specific API using pagination.
next_cursorstrThe last retrieved record ID for the next page. If no more records exist, it will be null.

Retrieving the first cursor

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

Example request
$curl https://api.yoco.com/v1/orders/?limit=2 \
>  -H 'Authorization: Bearer <access token>'
Example response
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

Example request with cursor
$curl https://api.yoco.com/v1/orders/?limit=2&cursor=MTczOTM3MDQwODg3NC0zNDJlMzlkMC1lMzY1LTQ2ZDAtYWZiMC1hODYxNTU5Mjg1ZGI%3D \
>  -H 'Authorization: Bearer <access token>'

Note that the cursor value is escaped when serializing over the HTTP parameter resulting in the = sign being replaced with %3D

Until, eventually, the next_cursor field is null

Example response with null cursor
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}

Changing filters while paginating will return results, but data consistency is not guaranteed.