> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developer.yoco.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developer.yoco.com/_mcp/server.

## Overview

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's 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:

Start by requesting the first page of data without the cursor set. If you don't provide a
`limit`, the API returns 50 records.

The response contains an array of records and a `next_cursor` field, which represents the next
set of data.

If the `next_cursor` is `null`, there are no more records to fetch.

To fetch the next page of data, provide the `cursor` value from the previous response as a query
parameter.

## Paginated request fields

| Field    | Type  | Description                                                  |
| -------- | ----- | ------------------------------------------------------------ |
| `limit`  | `int` | The number of records to return per page. The default is 50. |
| `cursor` | `str` | The cursor used to select the next set of data.              |

## Paginated response fields

| Field         | Type    | Description                                                                              |
| ------------- | ------- | ---------------------------------------------------------------------------------------- |
| `data`        | `array` | An array of records. Each record's data is defined in the specific API using pagination. |
| `next_cursor` | `str`   | The last retrieved record ID for the next page. If no more records exist, it's `null`.   |

## Retrieving the first cursor

Here's an example request and response format for an API endpoint when starting to list data:

**`Example request`**

```shell title="Example request"
curl https://api.yoco.com/v1/orders/?limit=2 \
  -H 'Authorization: Bearer <access token>'
```

**`Example response`**

```json title="Example response"
{
  "data": [
    {
      "id": "1633754596890-82bd44bb-ac03-428f-803f-bbffea92397c",
      "amounts": {
        "gross_amount": {
          "amount": 11500,
          "currency": "ZAR"
        }
      }
    },
    {
      "id": "1633754596890-0664eb40-a2d3-4095-bdc8-fa8267376bc3",
      "amounts": {
        "gross_amount": {
          "amount": 20700,
          "currency": "ZAR"
        }
      }
    }
  ],
  "next_cursor": "MTczOTM3MDQwODg3NC0zNDJlMzlkMC1lMzY1LTQ2ZDAtYWZiMC1hODYxNTU5Mjg1ZGI="
}
```

## Retrieving the next pages

**`Example request with cursor`**

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

> **Info**
>
> Note that the cursor value is escaped when serialising 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`**

```json title="Example response with null cursor"
{
  "data": [
    {
      "id": "1738754596890-29704755-1719-466c-8c4d-fe999e7b6c3a",
      "amounts": {
        "gross_amount": {
          "amount": 46850,
          "currency": "ZAR"
        }
      }
    },
    {
      "id": "1738754596890-6ed8ba62-4a79-41c5-81b5-156723d7fec3",
      "amounts": {
        "gross_amount": {
          "amount": 38106,
          "currency": "ZAR"
        }
      }
    }
  ],
  "next_cursor": null
}
```

> **Warning**
>
> Changing filters while paginating returns results, but data consistency isn't guaranteed.