> For the complete documentation index, see [llms.txt](https://docs.flowretail.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flowretail.com/docs/developers/pagination-and-sorting.md).

# Pagination & sorting

How list endpoints page, how to know when you are done, and how to sort.

Every list and search endpoint returns the same envelope: the results in `items`, the position in `paging`.

```json
{
  "items": [ ... ],
  "paging": {
    "totalCount": 27,
    "pageNumber": 1,
    "pageSize": 24
  }
}
```

| Field        | Meaning                                  |
| ------------ | ---------------------------------------- |
| `totalCount` | Total matching records across all pages  |
| `pageNumber` | The page you are on, counting from 1     |
| `pageSize`   | How many records were requested per page |

## Requesting a page

Around 160 endpoints accept these query parameters:

| Parameter    | Default | Notes                                        |
| ------------ | ------- | -------------------------------------------- |
| `pageNumber` | `1`     | One-based. Anything below 1 is treated as 1. |
| `pageSize`   | `1000`  | Anything below 1 falls back to the default.  |

```
GET /tenants/{tenantUid}/products?pageNumber=2&pageSize=100
```

**The default page size is 1000.** If you omit `pageSize` on a large collection you will pull a thousand records per request, which is usually not what you want. Set it deliberately.

There is no enforced upper limit on `pageSize`. That is not an invitation to request everything in one call — large pages are slow and can time out. Keep it to a few hundred for interactive work, and a few thousand at most for batch jobs.

## Knowing when you are done

There is no cursor and no `next` link. Two ways to stop:

* `items.length < pageSize` — you are on the last page.
* `pageNumber * pageSize >= totalCount` — the same conclusion from the counts.

```
pageNumber=1, pageSize=24, totalCount=27  ->  24 items, more to come
pageNumber=2, pageSize=24, totalCount=27  ->   3 items, done
```

## Paging is offset-based

The offset is computed as `pageSize * (pageNumber - 1)`. Records are not snapshotted between requests, so if data changes while you are paging, rows can shift between pages — a record inserted ahead of your position can push another onto a page you have already read, and you will miss it.

For a full export where completeness matters, either page by a stable sort on an immutable field, or accept that you may need a reconciliation pass. For incremental sync, prefer webhooks over re-paging the whole collection.

## Sorting

About 145 endpoints accept sorting:

| Parameter       | Values                             |
| --------------- | ---------------------------------- |
| `sortBy`        | A field name the endpoint supports |
| `sortDirection` | `ASC` or `DESC`                    |

```
GET /tenants/{tenantUid}/products?sortBy=name&sortDirection=ASC
```

Sortable fields vary by endpoint — check the endpoint's reference page. Two errors tell you when you have it wrong:

* `ErrInvalidSortBy` — that field cannot be sorted on here.
* `ErrInvalidSortDirection` — `sortDirection` was something other than `ASC` or `DESC`.

Sorting on a field that is not unique gives no guaranteed order within ties, and that order is not stable between requests. When paging a sorted list, sort on something unique — or add a unique tiebreaker — so pages line up.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.flowretail.com/docs/developers/pagination-and-sorting.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.