Response Patterns

Standard success, pagination, and error envelopes for the Merchants API.

Successful Merchants API responses use a consistent JSON envelope. List endpoints add pagination fields under data. Errors use a dedicated error object.

Single-item response

When an endpoint returns one resource, the body looks like:

{
  "data": { }
}

Optional fields on some success responses:

• error: boolean, set when the request failed (normally omitted on success)
• message: human-readable status text when present

Paginated response

List endpoints wrap a page of results:

{
  "data": {
    "items": [{ }, { }],
    "next": 2,
    "total": 10,
    "last_update": "2021-01-01T00:00:00Z"
  }
}

Field	Meaning
data.items	Resources on the current page
data.next	Next page number when more results exist
data.total	Total matching items across all pages
data.last_update	Timestamp of the most recently updated item in the set, when available

Common list query parameters (when supported by the endpoint):

Parameter	Meaning
page	1-based page number (default 1)
limit	Page size (default 100, maximum 100)
since / until	Inclusive created_at bounds (RFC3339)
sort	asc or desc for the primary sort key

Exact parameters differ per endpoint: see each operation in the interactive reference.

Error response

Failed requests return an error envelope:

{
  "error": {
    "code": 400,
    "message": "Insufficient quantity",
    "errors": [
      {
        "domain": "orders",
        "reason": "InsufficientQuantity"
      }
    ]
  }
}

Field	Meaning
error.code	Application / HTTP-style error code
error.message	Primary human-readable message
error.errors	Optional list of more specific domain / reason entries

HTTP status codes

Range	Meaning
2xx	Success
4xx	Client error (invalid input, auth, not found, etc.)
5xx	Server or upstream failure

Treat non-2xx responses as failures even if a body is present. Prefer handling by status code and error.code / error.message rather than string matching alone.

Next

• Authentication
• API Overview