Skip to main content
These conventions apply across the MerchantSpring Public API.

​
Format

  • HTTPS only.
  • Requests and responses are JSON. Send Content-Type: application/json on requests with a body.
  • Authenticate with your key in the x-api-key header on every request — see Authentication.
  • Most data endpoints are scoped to a channel by merchantId + channelId; discover these via POST /channels.

​
Pagination

Paginated endpoints (such as POST /content-changes) use zero-based pageIndex / pageSize:
ParameterDescription
pageIndexPage number, starting at 0 (default 0).
pageSizeItems per page. Defaults and caps vary by endpoint — e.g. content changes are capped at 500.
Always check the specific endpoint’s reference page for its exact defaults and maximum — and where the pagination parameters live, since some endpoints (e.g. content changes) nest pageIndex / pageSize under a paginationParams object.

​
Dates

Date ranges and timestamps are expressed in the format documented on each endpoint. Provide date-range parameters where an endpoint requires them (for example, the sales-by-period views), and prefer explicit ranges over relying on defaults.

​
Reports are asynchronous

Report creation (POST /reports/create/*) returns a reportId rather than the data itself. Poll GET /reports/status/{reportId} until status is done, then download the downloadUrl. See the Reports guide. Endpoints under /reports/view/* return JSON immediately and do not need polling.

​
Errors

The API uses standard HTTP status codes:
StatusMeaning
400Bad request — missing or invalid parameters.
401Valid API key, but it doesn’t have access to the endpoint.
403Missing or invalid API key.
404Resource not found (e.g. an unknown reportId).
Error responses include a message describing the problem.