Skip to content
Docs

Concepts

Requests and responses

  • Unknown query parameters fail with 400 unknown_parameter. A typo such as skus= never silently returns everything.
  • Repeat a parameter to send several values: ?sku=A&sku=B. Commas are part of a SKU, not separators.
  • Every documented field is always present. null means "no value", and lists are [], never null.
  • Ignore fields you don't recognise. We add fields within v1.
  • Expect new enum values in review, reviewed_by, status, availability and error codes. Treat an unknown value like the most cautious one you know.
  • Every GET endpoint also answers HEAD, with the same status and headers and no body.
  • GET responses carry a weak ETag and Cache-Control: private, max-age=60. Send the ETag back as If-None-Match to get 304 Not Modified, with no body, when nothing changed.
  • A single SKU link is the exception. GET and PUT /v1/sku-mappings/{sku} return a strong ETag, the link's version (such as "v42"), with Cache-Control: private, no-cache. Send it as If-Match to change the link only if nobody else has.
  • Every response has an X-Request-Id header, and every error body has the same value as request_id. Log it: it's the fastest way for support to find your request.
  • Percent-encode a SKU in a URL path: AB/12 X becomes /v1/sku-mappings/AB%2F12%20X. Python's urllib.parse.quote(sku, safe="") and JavaScript's encodeURIComponent(sku) both do this.