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.

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