> ## Documentation Index
> Fetch the complete documentation index at: https://developers.readyforcommerce.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Pagination

> Every list answers a page and a cursor to the next one: follow it until it is null.

Every operation that lists, such as [List exports](https://developers.readyforcommerce.com/api-reference/core-list-exports.md), answers one page at a time:

```json theme={null}
{
  "items": [{ "id": "6a1f0d3e-2c4b-4e7a-9f58-3b0c1d2e4a67", "state": "succeeded" }],
  "nextCursor": "[\"2026-11-12T09:30:00.000Z\",\"6a1f0d3e-2c4b-4e7a-9f58-3b0c1d2e4a67\"]"
}
```

* `items` holds the page's rows, in the list's order.
* `nextCursor` points to the next page, and is `null` on the last one.

## Read a whole list

Send `nextCursor` back as the `cursor` query parameter, as it came, and stop when it is `null`:

```bash curl theme={null}
# The first page; then send each page's nextCursor with --data-urlencode "cursor=…"
curl --get "https://app.readyforcommerce.com/api/v1/orgs/$RFC_ORG_ID/core/exports" \
  --data-urlencode "limit=20" \
  --header "Authorization: Bearer $RFC_API_KEY"
```

```python Python theme={null}
import os

import requests

url = f"https://app.readyforcommerce.com/api/v1/orgs/{os.environ['RFC_ORG_ID']}/core/exports"
headers = {"Authorization": f"Bearer {os.environ['RFC_API_KEY']}"}
params = {"limit": 20}
while True:
    page = requests.get(url, params=params, headers=headers).json()
    for export in page["items"]:
        print(export["id"])
    if page["nextCursor"] is None:
        break
    params["cursor"] = page["nextCursor"]
```

```php PHP theme={null}
<?php
$url = 'https://app.readyforcommerce.com/api/v1/orgs/' . getenv('RFC_ORG_ID') . '/core/exports';
$query = ['limit' => 20];
do {
    $curl = curl_init($url . '?' . http_build_query($query));
    curl_setopt_array($curl, [
        CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('RFC_API_KEY')],
        CURLOPT_RETURNTRANSFER => true,
    ]);
    $page = json_decode(curl_exec($curl), true);
    foreach ($page['items'] as $export) {
        echo $export['id'] . PHP_EOL;
    }
    $query['cursor'] = $page['nextCursor'];
} while ($page['nextCursor'] !== null);
```

```javascript JavaScript theme={null}
const url = new URL(
  `https://app.readyforcommerce.com/api/v1/orgs/${process.env.RFC_ORG_ID}/core/exports`,
);
url.searchParams.set('limit', '20');
for (;;) {
  const response = await fetch(url, {
    headers: { Authorization: `Bearer ${process.env.RFC_API_KEY}` },
  });
  const page = await response.json();
  for (const item of page.items) console.log(item.id);
  if (page.nextCursor === null) break;
  url.searchParams.set('cursor', page.nextCursor);
}
```

> [!NOTE]
>
> A cursor is opaque: send it as it came, and never build or change one. A cursor that is not one
> the API gave answers `422 core.validation_failed`. There are no page numbers: a cursor goes on
> from the last row you read, so a row added while you read never makes another row repeat or go
> missing.

## Page size and total

| Parameter | What it does |
| - | - |
| `limit` | The rows of a page: at most 200, and 200 when you send none. |
| `withTotal=true` | Adds `total` to the answer: how many rows the whole list holds. Send it only when you need it, since counting takes longer than reading a page. |

## Search, filter and order

Some lists take `q`, a JSON object that searches, filters and orders them, such as
[List exports](https://developers.readyforcommerce.com/api-reference/core-list-exports.md), [List imports](https://developers.readyforcommerce.com/api-reference/core-list-imports.md) and
[List incidents](https://developers.readyforcommerce.com/api-reference/core-list-incidents.md). Each one's page says what its search reads and which fields
its filter takes. This `q` finds the exports whose file name holds *prices* and that succeeded:

```json theme={null}
{
  "search": "prices",
  "filter": { "logic": "and", "items": [{ "field": "state", "op": "eq", "value": "succeeded" }] }
}
```

`filter.logic` is `and` (every condition) or `or` (any of them), and `sort` orders the list by one field:
`{ "field": …, "direction": "asc" }`, or `"desc"`.

Send it URL-encoded, as `q=…`, with the same `q` on every page of the same list.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.