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

# Pagination

> Page through any list in the storekit API with cursors: the list object, the limit, starting_after and ending_before parameters, and how to check for new items.

Every endpoint that returns a list is paginated the same way, with cursors. There are no page numbers and no offsets.

## The List Object

```json theme={null}
{
    "object": "list",
    "data": [
        { "id": "ord_…", "object": "order" },
        { "id": "ord_…", "object": "order" }
    ],
    "has_more": true,
    "next_cursor": "c9J2…",
    "previous_cursor": "x1Qe…"
}
```

| Field | Type | Meaning |
| - | - | - |
| `object` | string | Always `list`. |
| `data` | array | The items on this page. Empty when there are none. |
| `has_more` | boolean | Whether more items follow in the direction you are paging. |
| `next_cursor` | string or `null` | Pass it as `starting_after` to fetch the items after this page. `null` only when the page is empty. |
| `previous_cursor` | string or `null` | Pass it as `ending_before` to fetch the items before this page. `null` only when the page is empty. |

## Parameters

| Parameter | Type | Meaning |
| - | - | - |
| `limit` | integer | How many items to return, from 1 to 100. Defaults to 20. |
| `starting_after` | string | The `next_cursor` of a page. Returns the items after that page. |
| `ending_before` | string | The `previous_cursor` of a page. Returns the items before that page. |

Send `starting_after` or `ending_before`, never both. Without either, you get the first page.

## Read a Whole List

Fetch the first page, then keep passing `next_cursor` as `starting_after` until `has_more` is `false`:

```bash theme={null}
curl "https://api.storekit.com/v1/orders?limit=100" \
  -H "Authorization: Bearer $API_KEY"

curl "https://api.storekit.com/v1/orders?limit=100&starting_after=c9J2…" \
  -H "Authorization: Bearer $API_KEY"
```

```javascript theme={null}
const listAll = async path => {
    const items = [];
    let startingAfter = null;

    do {
        const url = new URL(path, 'https://api.storekit.com');
        url.searchParams.set('limit', '100');

        if (startingAfter) {
            url.searchParams.set('starting_after', startingAfter);
        }

        const response = await fetch(url, {
            headers: { Authorization: `Bearer ${process.env.API_KEY}` }
        });

        if (!response.ok) {
            throw new Error(`Request ${response.headers.get('Request-Id')} failed`);
        }

        const page = await response.json();

        items.push(...page.data);
        startingAfter = page.has_more ? page.next_cursor : null;
    } while (startingAfter);

    return items;
};
```

Stop when `has_more` is `false`. Do not work it out from the number of items on a page or from the cursors: the last page still has a `next_cursor`.

## Order

A list is sorted newest first unless the endpoint says otherwise. An endpoint that lets you choose the order documents its own `sort` parameter.

**New items do not shift the pages.** A cursor marks a position in the list, not a count of items to skip. If items are created while you are paging, the next page still starts right after the last item you saw: nothing is repeated and nothing is skipped.

## Cursors

* **A cursor is opaque.** Do not parse it, build it or change it. Store it as a string of up to 512 characters.
* **A cursor belongs to the request that returned it.** Use it with the same endpoint, the same filters and the same sort. To change a filter or the sort, start again from the first page.
* A cursor works only with a key of the account it was issued to.

A cursor that was not issued by this list for this request (one that was changed, or that came from another list, another account, another set of filters or another sort) is answered with `400` and the code `cursor_invalid`:

```json theme={null}
{
    "error": {
        "type": "invalid_request_error",
        "code": "cursor_invalid",
        "message": "The cursor in starting_after is not valid for this list, these filters and this sort. Use a cursor from a response to the same request, or start again without one.",
        "param": "starting_after",
        "doc_url": "https://docs.storekit.com/developers/api/errors#cursor_invalid",
        "request_id": "req_019a8f3b2c4d7e6f8a9b0c1d2e3f4a5b"
    }
}
```

`param` is `starting_after` or `ending_before`, whichever held the cursor. Handle `cursor_invalid` by starting the list again without a cursor: the same cursor will not work on a retry. A cursor can also stop being valid over time, so do not rely on one you stored long ago.

The other pagination mistakes are answered with `400` and `parameter_invalid`, with `param` naming the parameter: sending both `starting_after` and `ending_before`, a cursor that is empty or longer than 512 characters, and a `limit` outside 1 to 100. See [Errors](https://storekit.com/docs/developers/api/errors).

## Page Backwards

Pass a page's `previous_cursor` as `ending_before` to get the items before it. The items on that page are in the list's usual order, and `has_more` says whether more items lie further back.

## Check for New Items

Both cursors are set on every page that has items. So the first page of a newest-first list has a `previous_cursor`, even though nothing is before it yet. Keep that cursor and pass it as `ending_before` later to fetch only the items created since:

1. Fetch the first page and store its `previous_cursor`.
2. Later, request the list with `ending_before` set to the stored cursor.
3. If `data` is empty, nothing is new. Keep the cursor you have: an empty page has both cursors `null`.
4. Otherwise process the items and store the page's `previous_cursor` in place of the one you had.
5. If `has_more` is `true`, request the list again with the new cursor, and repeat until it is `false`.

A stored cursor does not last for ever. If a request with it is answered with `cursor_invalid`, read the list from the first page again and store the new `previous_cursor`. Make sure processing an item twice is harmless, for example by keeping the IDs you have already handled.

## Summary of the Cursor Fields

| | `has_more` | `next_cursor` | `previous_cursor` |
| - | - | - | - |
| Page with items, more to come | `true` | Set | Set |
| Page with items, nothing more | `false` | Set | Set |
| Empty page | `false` | `null` | `null` |


## Related topics

- [Response Format](https://storekit.com/docs/developers/mcp/response-format.md)
- [Format de réponse](https://storekit.com/docs/fr/developers/mcp/response-format.md)
- [Merchant MCP Overview](https://storekit.com/docs/developers/mcp/overview.md)
- [Aperçu du MCP marchand](https://storekit.com/docs/fr/developers/mcp/overview.md)
- [Tools](https://storekit.com/docs/nl/developers/mcp/tools.md)


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