Skip to content

Pagination and search

Cursors, filters, sorts, search, counts and facets on every list.

Updated

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

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

Pages

  • limit sets the page size, up to the list’s maximum; its 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".
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"
const answer = await sherpo('GET', '/v1/stores/STORE_ID/products', {
  query: [
    ['filter[status]', 'published'],
    ['sort', 'published'],
    ['limit', '2'],
    ['count', 'true'],
  ],
});

Answers 200, abridged:

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

// 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, 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=<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.
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"
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, GET /categories and GET /integrations answer every row, and GET /payouts pages with a cursor of its own and sends no Link header. Each one’s reference page shows what it answers.

Type to search…

↑↓ navigate↵ selectEsc close