Cursor-Based Pagination

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude

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.

{
  "_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):

{
  "items": [
    // Resource objects
  ],
  "pagination": { 
    "nextCursorToken": "eyJpZCI6IjBkMWEzNzdiLWI0YzUtNGE5NC05ZTJlLTgzZTU5ZDFmNmE5YyIsImNyZWF0ZWREYXRlIjoiMjAyNS0wNy0wMlQxMjozNDo1NloifQ==", 
    "previousCursorToken": null, 
  }
}

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.
   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.
   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