---
title: "Requests and answers"
description: "Paths, how arguments travel, what answers look like and the limits on a request."
---

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

# Requests and answers

## Paths

Every path is under the API's base, `https://api.sherpo.io/merchant`, and starts with `/v1` (see [versioning](/merchant-api/versioning)):

- **A store's operations** are under `/v1/stores/{store}`, where `{store}` is the store's id, as <a href="/merchant-api/reference/list-merchants/">`GET /v1/merchants`</a> lists them: `GET /v1/stores/{store}/products`, `POST /v1/stores/{store}/products/{product}/publish`.
- **The business** is `GET /v1/merchants` and `GET /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: <a href="/merchant-api/reference/update-tier/">`PATCH /products/{product}/tiers/{tier}`</a>, <a href="/merchant-api/reference/get-entry/">`GET /products/{product}/entries/{entry}`</a>, and a quiz under its entry too, <a href="/merchant-api/reference/get-quiz/">`GET /products/{product}/entries/{entry}/quizzes/{quiz}`</a>. 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`](/merchant-api/errors#not_found).

Some lists answer for the whole store and for one product, as two operations: <a href="/merchant-api/reference/list-reviews/">`GET /reviews`</a> lists every product's reviews, and <a href="/merchant-api/reference/list-product-reviews/">`GET /products/{product}/reviews`</a> 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 <a href="/merchant-api/reference/list-certificates/">`GET /products/{product}/certificates`</a>.

A path that answers no operation is `404` [`not_found`](/merchant-api/errors#not_found); a path that answers other methods is `405` [`method_not_allowed`](/merchant-api/errors#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](/merchant-api/files#fetch-a-files-bytes)).

## 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>`, or `product=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 `POST` to its `/query` path with a JSON body, like <a href="/merchant-api/reference/list-resource-access/">`POST /access_requirements/query`</a>. It still only reads, which the OpenAPI document marks with `x-read-only: true`.

Each operation's arguments, their types and limits are in its [reference](/merchant-api/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`](/merchant-api/errors#invalid), with `context.path` pointing at it (`["body", "title"]`, `["query", "limit"]`).

## Answers

A call answers JSON: `201` for an operation named `create` or `record` (<a href="/merchant-api/reference/create-product/">`POST /products`</a>, <a href="/merchant-api/reference/record-order/">`POST /orders`</a>), `200` for every other, granting access and attaching a file included. Each operation's [reference](/merchant-api/reference) page names its status. A failure answers a [problem](/merchant-api/errors) 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 takes `YYYY-MM-DD`.
- **Money** is an integer in minor units with the `exponent` that scales it and the `currency` (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](/merchant-api/rich-text).
- **Enum values** may grow within `/v1`: treat a value you don't know as "other", never as an error. See [versioning](/merchant-api/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 (<a href="/merchant-api/reference/set-body/">`PUT /{kind}/{id}/body`</a>, <a href="/merchant-api/reference/edit-body/">its edit</a>, <a href="/merchant-api/reference/publish-body/">its publish</a>) 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](/merchant-api/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 `413` with the problem type `invalid`.
- A body nesting deeper than 64 levels, or holding more than 100,000 objects and arrays or 100,000 values, answers `422` `invalid`.
- Calls are metered per token, on each store on its own: see [rate limits](/merchant-api/rate-limits).

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