Every list below answers a page at a time, with a cursor to the next one. Two reads aren’t paged: GET /contacts answers an array, and GET /prompts answers { items, truncated }, where truncated: true means the list was cut short.
curl 'https://api.sherpo.io/customer/v1/stores/yourstore.sherpo.io/products/slug:intro-course/entries?limit=2&count=true' \
--header 'Publishable-Key: <publishable key>'{
"items": [
{ "id": "<entry id>", "slug": "welcome", "title": "Welcome", "position": 0, "access": "unlocked" },
{ "id": "<entry id>", "slug": "setting-up", "title": "Setting up", "position": 1, "access": "locked" }
],
"cursor": "eyJrIjpbMV19",
"total": 12
}Here and in every guide, an example answer is trimmed to the fields it’s about; the reference lists every field.
Pages
| Parameter | |
|---|---|
limit |
Items per page: 20 unless you ask, at most 100. A portfolio’s snapshots page 100 at a time, at most 400. |
cursor |
The cursor of the page before, to read the next one. Leave it out for the first page. |
count |
true adds total, how many items match in all. |
A page answers { items, cursor }, and total when you asked for it. On a product’s reviews, total counts the reviews shown, so it can be lower than the product’s rating.count, which counts every rating. While cursor isn’t null, more items follow: pass it back, with the same filters, sort and search, for the next page. The answer also names the next page in a Link: <...>; rel="next" header. A cursor of null is the end.
Sort
sort names one of the list’s orders (below), and direction (asc or desc) the direction of its leading field; asking for the other direction reverses the whole order. Without sort, a list takes its default order.
Filters
filter[<field>]=<value> keeps the items whose field equals the value. filter[<field>][<op>]=<value> names the operator:
eq: equals, the same asfilter[<field>]=<value>;in: equals any of the values, the parameter repeated once per value;gteandlte: at least, and at most.
filter[status][in]=active&filter[status][in]=past_due
filter[occurred_at][gte]=2026-01-01T00:00:00.000Z
filter[rating][gte]=4A timestamp is an ISO 8601 time, a date a calendar day (2026-11-03), a boolean true or false. A filter, operator, sort or value the list doesn’t declare is refused as 422 invalid, never ignored.
Search
search=<words> keeps the items whose fields match, on lists that offer it (below), and takes up to 200 characters; a longer one is refused as invalid. While searching, an empty page that still has a cursor means nothing matched so far, not the end: keep paging until cursor is null. A searched page past the counting budget comes back without total, even when you asked for it, which never means zero.
What each list takes
| List | Filters | Sorts | Search |
|---|---|---|---|
| Products | category (eq, in), listing (eq: primary, secondary) |
catalog, published, title |
title, subtitle |
| Entries | section (eq, in), tag (eq, in, ignoring case), published_at (gte, lte) |
position, published |
title, subtitle, preview |
| Entry sections | value |
value |
|
| Entry tags | value |
value |
|
| Pages | in_menu (eq) |
title, menu |
title, description |
| Completions | product_id (eq) |
completed |
|
| Notifications | read (eq), type (eq, in: portfolio_trade, new_lesson, new_episode, new_post, new_file, new_product, new_discount, event_reminder, event_follow_up) |
created |
|
| Checkouts | status (eq, in: open, frozen, paid, abandoned, expired), currency (eq) |
created |
|
| Orders | source (eq, in: checkout, api, manual), occurred_at (gte, lte) |
occurred |
|
| Order lines | line |
||
| Order refunds | occurred |
||
| Subscriptions | status (eq, in: active, past_due, paused, cancelled, ended, unpaid), product_id (eq) |
created |
|
| Grants | product_id (eq) |
valid_from |
|
| Entitlements | product_id (eq) |
product, title |
|
| Reviews | rating (eq, in, gte, lte) |
created, rating |
|
| Quiz attempts | entry_id (eq), quiz_id (eq), status (eq, in: started, passed, failed, forfeited) |
started |
|
| Certificates | product_id (eq), entry_id (eq) |
issued |
|
| Licenses | created |
||
| License devices | status (eq, in: active, inactive, deactivated) |
activated, last_seen |
|
| Portfolio events | type (eq, in), symbol (eq, in), occurred_at (gte, lte) |
occurred |
symbol, note, name |
| Software activity | type (eq, in: release, note), occurred_at (gte, lte) |
occurred |
version, body |
| Portfolio snapshots | date (gte, lte) |
date |
Each list’s first sort is its default, except a blog’s or a podcast’s entries, which list newest first (published).
Completions, quiz attempts and certificates list the customer’s across every product at the top level, and one product’s under it, with the same filters and sorts: GET /products/{product}/completions, GET /products/{product}/attempts and GET /products/{product}/certificates. Prompts do the same, at GET /prompts and GET /products/{product}/prompts.
A read’s other arguments
A read (GET) takes its arguments in the query string:
- a scalar as it is:
runnable=true,coupon=WELCOME10; - an object one level deep, each field in brackets:
target[kind]=entry&target[id]=<entry id>; - an array by repeating the parameter:
include=body,kinds=summary&kinds=chapters; - a reference as its id, or
slug:<slug>where the kind has slugs:product=slug:intro-course.
A write (POST, PUT, PATCH, DELETE) takes its other arguments, if any, in a JSON body; the ids its path names stay out of it.