---
title: "Pagination and search"
description: "Cursors, filters, sorts, search, counts and facets on every list."
---

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

# Pagination and search

Every list over a collection (products, orders, customers, grants, webhook deliveries and the rest) takes the same query parameters and answers the same envelope:

```json
{ "items": [...], "cursor": "eyJrIjpbMCwiNmYxYyJdfQ", "total": 14, "facets": { ... } }
```

## Pages

- `limit` sets the page size, up to the list's maximum; its [reference](/merchant-api/reference) page names its default and maximum.
- `cursor` is the next page's cursor, or `null` on the last page. Pass it back as `cursor` with the same other parameters to read the next page; a cursor is opaque, so never build or change one.
- While `cursor` is not `null`, the answer also carries a `Link` header naming the next page: `Link: <...&cursor=eyJr...>; rel="next"`.

```bash
curl -g 'https://api.sherpo.io/merchant/v1/stores/STORE_ID/products?filter[status]=published&sort=published&limit=2&count=true' \
  -H "Authorization: Bearer $SHERPO_TOKEN"
```

```js
const answer = await sherpo('GET', '/v1/stores/STORE_ID/products', {
  query: [
    ['filter[status]', 'published'],
    ['sort', 'published'],
    ['limit', '2'],
    ['count', 'true'],
  ],
});
```

Answers `200`, abridged:

```json
{
  "items": [
    {
      "id": "6f1c2a9e-4b7d-4e2a-9c51-0d3e8b7a1f42",
      "slug": "watercolor-basics",
      "title": "Watercolor basics",
      "category": "course",
      "status": "published",
      "priority": 0,
      "published_at": "2026-04-01T08:00:00.000Z"
    }
  ],
  "cursor": "eyJrIjpbMCwiNmYxYyJdfQ",
  "total": 14
}
```

To read a whole list, follow the cursor until it is `null`:

```js
// Yields each page of a list, following its cursor until it is null.
async function* pages(path, query = []) {
  let cursor = null;
  do {
    const page = await sherpo('GET', path, {
      query: cursor === null ? query : [...query, ['cursor', cursor]],
    });
    if (page.cursor === undefined) throw new Error(`${path} answered no cursor, so it is no list to page.`);
    yield page;
    cursor = page.cursor;
  } while (cursor !== null);
}

for await (const page of pages('/v1/stores/STORE_ID/customers', [['limit', '100']])) {
  for (const customer of page.items) console.log(customer.email);
}
```

## Filters

`filter[<field>]=<value>` keeps the rows whose field equals the value. Other operators go after the field:

- `filter[<field>][in]=<value>`, repeated for each value (`filter[status][in]=draft&filter[status][in]=scheduled`), keeps rows matching any of them. A call's `in` filters list at most 50 values in all.
- `filter[<field>][gte]=<value>` and `filter[<field>][lte]=<value>` bound a number, a time or a date, inclusive.

Which fields each list filters on, with which operators, is in its reference page. A filter, sort or facet the list doesn't declare is refused as [`invalid`](/merchant-api/errors#invalid), never ignored. A few lists only make sense within something: webhook deliveries within an endpoint (`filter[webhook_id]`), a subscription's periods within the subscription. Such a list refuses a call that names none of the fields its reference lists.

## Sorts

`sort=<name>` picks one of the list's named sorts, each with a natural direction (`sort=published` is newest first). `direction=asc` or `direction=desc` names the direction of the sort's first column; asking for the other one reverses the whole sort, so `sort=published&direction=asc` is oldest first. Where a sort's reference pins rows with no value first or last, they stay there whichever the direction. Without `sort`, a list uses its default (a blog's entries list its drafts first, then newest first, as `sort=latest` does; a podcast's newest first, drafts last, as `sort=published` does; any other product's in their order), and rows that tie are ordered by id, so the pages of a list that isn't changing follow each other without overlap.

## Search

`search=<text>` narrows a list that declares search (products by title, slug and subtitle; orders by number, note and source key) to the rows matching the text. Which fields each list searches is in its reference page. A search takes up to 200 characters; a longer one is refused as `invalid`.

On a list that searches customers, a search written as a phone number (at least 7 digits, with only spaces, dashes, dots, parentheses, slashes or plus signs among them) finds a customer's phone by its digits, however either is written, and never by the text of a name, an email or another phone. On orders, such a search with separators still reads an order's own note and source key as written, and one of digits alone finds the order of that number, the order whose source key is those digits, or a customer's phone.

A searched page can come back empty with a `cursor`: that means nothing matched so far, not the end. Only `cursor: null` ends a search, so keep following the cursor.

## Counts and facets

- `count=true` adds `total`, how many rows match the filters.
- `facets=<field>`, repeated for each field, adds `facets`: for each field, how many rows hold each value. Each facet counts the rows matching the search and every other filter but its own field's, so `filter[status]=draft&facets=status` still counts every status, the way a filter menu shows its options. Only the fields a list's reference names as facets take it.

```bash
curl -g 'https://api.sherpo.io/merchant/v1/stores/STORE_ID/products?filter[status][in]=draft&filter[status][in]=scheduled&search=watercolor&facets=status' \
  -H "Authorization: Bearer $SHERPO_TOKEN"
```

```js
const answer = await sherpo('GET', '/v1/stores/STORE_ID/products', {
  query: [
    ['filter[status][in]', 'draft'],
    ['filter[status][in]', 'scheduled'],
    ['search', 'watercolor'],
    ['facets', 'status'],
  ],
});
```

A searched page past the counting budget comes back without `total` and `facets` even when asked; that never means zero.

## Other lists

Some reads answer their own shape, without the envelope or a cursor, because they are short or paged another way. For example, <a href="/merchant-api/reference/list-categories/">`GET /categories`</a> and <a href="/merchant-api/reference/list-integrations/">`GET /integrations`</a> answer every row, and <a href="/merchant-api/reference/list-payouts/">`GET /payouts`</a> pages with a `cursor` of its own and sends no `Link` header. Each one's reference page shows what it answers.

Source: https://docs.sherpo.io/merchant-api/pagination/index.mdx
