# Pagination

> Lists are cursor-paginated, newest first, and stable while new items arrive.

Source: https://shopfa.st/docs/guides/pagination

Every list endpoint answers:

```json
{ "items": [ … ], "nextCursor": "WyIyMDI2LTEwLTIxVDEyOjAwOjAwLjAwMFoiLCJvcmRfLi4uIl0" }
```

Pass `nextCursor` back as `cursor` until it is `null`. Set the page size with `limit` (most lists allow 1 to 100,
default 50).

```ts
async function* allOrders() {
  let cursor: string | null = null;
  do {
    const qs = new URLSearchParams({ limit: '100', ...(cursor === null ? {} : { cursor }) });
    const res = await fetch(`https://api.shopfa.st/v1/store/orders?${qs}`, { headers: { Authorization: `Bearer ${KEY}` } });
    const page = await res.json();
    yield* page.items;
    cursor = page.nextCursor;
  } while (cursor !== null);
}
```

- Cursors are **keyset** positions (time and id), not offsets: items created while you page never shift or repeat
  what you already read.
- Cursors are **opaque**. Do not build or parse them; a modified cursor answers `422`.
- Filters (`tab`, `q`, `status`…) must stay the same across pages.
- Some lists also return counts per tab next to `items`, for the whole filter, not just the page.