# Cursor-Based Pagination

## Pagination improvements

To enhance the performance and reliability of our API, we are progressively migrating our List methods to cursor-based pagination. This upgrade is designed to provide a more stable and efficient experience, especially when dealing with large volumes of data.

Deprecated Structure
Cursor-based pagination will **replace** the previous `_links` and `metadata` objects:


```json Deprecated Pagination Structure
{
  "_links": {
    "first": "/{resource}?limit=20",
    "last": "/{resource}?page=4&limit=20",
    "next": "/{resource}?page=3&limit=20",
    "previous": "/{resource}?page=2&limit=20"
  },
  "metadata": {
    "totalItems": 100,
    "itemCount": 10,
    "itemsPerPage": 10,
    "totalPages": 10,
    "currentPage": 1
  }
}
```

## How It Works

### Structure

With the introduction of cursor-based pagination, the structure of our API responses for List methods will be updated. Here’s a look at the new format (see the pagination key):


```json Cursor Token Example
{
  "items": [
    // Resource objects
  ],
  "pagination": { // [!code highlight]
    "nextCursorToken": "eyJpZCI6IjBkMWEzNzdiLWI0YzUtNGE5NC05ZTJlLTgzZTU5ZDFmNmE5YyIsImNyZWF0ZWREYXRlIjoiMjAyNS0wNy0wMlQxMjozNDo1NloifQ==", // [!code highlight]
    "previousCursorToken": null, // [!code highlight]
  }
}
```

### Navigating Results

To navigate through paginated results, you will use the `nextCursorToken` (or `previousCursorToken`) from one response as a parameter in your next request. For example:

1. **Initial Request**: Your first request to a List endpoint will not include a `nextCursorToken`.

```shell Initial API Call
curl GET baseUrl/account_movements?limit=100
```
2. **Subsequent Requests**: To retrieve the next set of results, take the `nextCursorToken` value from the pagination object in the response and use it as the `nextCursorToken` query parameter in your next call. In the case that you want the previous set of results, take the `previousCursorToken` value instead and pass it as the `previousCursorToken` query parameter.

```shell Subsequent API Calls
# Going Forward
GET baseUrl/account_movements?limit=100&nextCursorToken={pagination.nextCursorToken}

# Going Backwards
GET baseUrl/account_movements?limit=100&previousCursorToken={pagination.previousCursorToken}
```


You can continue making requests with the new `nextCursorToken` or `previousCursorToken` from each response until value of the field is `null` (indicating that there are no more results).

## Currently Supported Endpoints

We are rolling out this improvement across our API. The following List methods currently support cursor-based pagination:

- `GET baseUrl/account_movements` (In Production August 5, 2025)
- `GET baseUrl/payment_requests` (In Production August 5, 2025)
- `GET baseUrl/payment_methods` (In Production August 8, 2025 )
- `GET baseUrl/customers` (In Production August 22, 2025)
- `GET baseUrl/consents` (In Production August 22, 2025)


## How to Adopt the New Pagination

We've designed the transition to be as smooth as possible.

- **For New Clients:** Cursor-based pagination is enabled by default for all new clients.
- **For Existing Clients:** Once you have updated your integration to handle the new pagination response and request format, please contact our support team. We will then activate this feature for your account.


## Migration Checklist

- [ ] Update response parsing to use `pagination` object
- [ ] Replace page-based logic with cursor token handling
- [ ] Test with your existing filters and sorting
- [ ] Contact support to enable cursor pagination