Paths
Every path is under the API’s base, https://api.sherpo.io/merchant, and starts with /v1 (see versioning):
- A store’s operations are under
/v1/stores/{store}, where{store}is the store’s id, asGET /v1/merchantslists them:GET /v1/stores/{store}/products,POST /v1/stores/{store}/products/{product}/publish. - The business is
GET /v1/merchantsandGET /v1/merchants/{merchant}.
A row is named by its id in the path (/products/{product}). Products and the other kinds whose reference says so also take their slug as slug:<slug>, so /products/slug:watercolor-basics names the product whose slug is watercolor-basics. An entry’s slug is unique only within its product, so /products/{product}/entries/{entry} takes its id alone.
A row that belongs to a product is named under it: PATCH /products/{product}/tiers/{tier}, GET /products/{product}/entries/{entry}, and a quiz under its entry too, GET /products/{product}/entries/{entry}/quizzes/{quiz}. The same holds for prices, prompts, reviews, attempts, certificates and their issues, feeds, an event’s sessions and a portfolio’s holdings. A row that isn’t the named product’s (or a quiz that isn’t the named entry’s) answers 404 not_found.
Some lists answer for the whole store and for one product, as two operations: GET /reviews lists every product’s reviews, and GET /products/{product}/reviews one product’s. The store-wide lists are /reviews, /reviews/stats, /tiers, /prices, /certificates/issues, /attempts and /feeds, each also under /products/{product}. A product’s certificates are listed under it alone, at GET /products/{product}/certificates.
A path that answers no operation is 404 not_found; a path that answers other methods is 405 method_not_allowed, with an Allow header listing them. A HEAD answers as its GET does, without the body, except on a file’s URL, which takes GET alone (see files).
Arguments
- Path parameters name the rows the call acts on.
- A write’s other arguments are a JSON object in the body. Send
Content-Type: application/json; an operation that takes nothing but its path takes an empty body or{}. - A read’s or a delete’s other arguments go in the query string: scalars as they are (
limit=50), objects one level deep (span[from]=2026-11-01), arrays as the parameter repeated (ids=a&ids=b), and a reference to a row as its id (product=<id>, orproduct=slug:<slug>). Percent-encode each value on its own, so a value holding a comma stays one value. - A read whose arguments don’t fit the query string (an array of objects) is a
POSTto its/querypath with a JSON body, likePOST /access_requirements/query. It still only reads, which the OpenAPI document marks withx-read-only: true.
Each operation’s arguments, their types and limits are in its reference page. An argument an operation doesn’t take, a value outside its limits, or a body that isn’t a JSON object is refused as 422 invalid, with context.path pointing at it (["body", "title"], ["query", "limit"]).
Answers
A call answers JSON: 201 for an operation named create or record (POST /products, POST /orders), 200 for every other, granting access and attaching a file included. Each operation’s reference page names its status. A failure answers a problem instead.
- Names are
snake_case. - Times are ISO 8601 strings in UTC (
2026-11-03T10:00:00.000Z). A time you send may carry an offset (2026-12-01T09:00:00+01:00), and a date-only filter takesYYYY-MM-DD. - Money is an integer in minor units with the
exponentthat scales it and thecurrency(lowercase ISO 4217):{ "amount": 4900, "exponent": 2, "currency": "eur" }is 49.00 euros. Send amounts the same way. - Ids are opaque strings. Store them as they are; never parse them.
- Rich text fields come back as HTML in one closed format. See rich text.
- Enum values may grow within
/v1: treat a value you don’t know as “other”, never as an error. See versioning.
Short answers
A write that takes a long text or binds files answers short, so you don’t pay for what you just sent: a body write (PUT /{kind}/{id}/body, its edit, its publish) answers its attachment, the asset it holds now (the from of your next write) and the attachments it created, with the preview link a set or an edit answers and the blocks an edit touched; a product, entry, page or quiz write answers the record without its long texts, attachments and files, with the attachments its texts created. Pass full: true with the write to have them answered too, as its read answers them. Each operation’s reference page marks what only full answers.
Every write answers Cache-Control: no-store, so no cache keeps what it answered (a webhook’s signing secret among them).
Limits on a request
- A body of more than 16 MiB answers
413with the problem typeinvalid. - A body nesting deeper than 64 levels, or holding more than 100,000 objects and arrays or 100,000 values, answers
422invalid. - Calls are metered per token, on each store on its own: see rate limits.