Full dump

GET /api/v1/merchant/items/full-dump

Entire active catalogue in a single response, normally regenerated about every two minutes. Use generated_at to judge freshness; regeneration timing is not a delivery guarantee. Use this for bulk sync instead of walking /items page by page.

Requires Authorization: Bearer mer_live_… (Authentication).

Headers

Header	Direction	Notes
`If-None-Match`	request	Send the previous `ETag` to receive `304 Not Modified`.
`Accept-Encoding`	request	Send `gzip` to reduce transfer size; catalog size varies.
`ETag`	response	Weak ETag (`W/"…"`) of the current dump. Returned on `200` and `304`; save and resend the exact string.
`Last-Modified`	response	HTTP-date of the last regeneration; `200` only.
`X-Items-Count`	response	Total items in the dump; `200` only.
`X-Catalog-Cursor`	response	Replay cursor captured before reading the database; use it with the realtime feed. Also returned on `304`.
`X-Catalog-Epoch`	response	Engine epoch associated with that cursor. Both cursor headers are absent when generation crosses an engine restart or the stream is unavailable.
`Content-Encoding`	response	`gzip` when the client advertised it; otherwise omitted.

Example

⚠️

Send Accept-Encoding: gzip. A full catalog is large and changes in size. Pair it with If-None-Match after the first completed download to skip the body (304) when the cached snapshot still matches.

# First download: keep the response headers and write into a temporary file.
# --compressed asks curl to decode gzip. Inspect the status and validate the complete JSON
# and item count before replacing your working snapshot and its metadata.
curl --compressed "https://merchant-api.tradeon.market/api/v1/merchant/items/full-dump" \
  -H "Authorization: Bearer mer_live_…" \
  -H "Accept-Encoding: gzip" \
  --fail-with-body \
  -D catalogue.headers.tmp \
  -o catalogue.json.tmp

For later requests, send the saved ETag verbatim, including W/ and quotes, in If-None-Match (for example If-None-Match: W/"saved-value"). Keep the old snapshot until its replacement is fully downloaded and parsed. Save ETag, cursor and epoch together with the snapshot, not independently.

200 OK body, with the item array shortened for readability:

{
  "generated_at": "2026-06-24T18:00:00.000Z",
  "items_count": 2382005,
  "items": [ /* ... CatalogItem objects ... */ ]
}

Each entry follows the CatalogItem schema. JSON object field order is not guaranteed: items_count may follow the items array. If you parse the response as a stream, use X-Items-Count for the count before reading the body.

304 Not Modified has no body. Keep the existing snapshot; the response includes ETag and, when available, its matching cursor/epoch pair. It does not include Last-Modified or X-Items-Count. Never replace your snapshot with an empty 304 body.

The body and response metadata belong to the same snapshot, even when a new dump is published during your download. If a complete snapshot cannot be prepared or download capacity is temporarily exhausted, the endpoint returns 503 FEED_NOT_READY before starting the body. Retry with backoff and keep your last complete snapshot.

For continuous synchronization, apply this dump, then connect to the realtime feed with its X-Catalog-Cursor and retain X-Catalog-Epoch for the handshake. Apply replay before entering live processing. Do not substitute the current stream head for the dump’s cursor. If the pair is absent, the REST snapshot is still usable, but wait for a fresh dump with both headers before starting a continuous stream. A resync request or epoch change requires a new snapshot; see catalog synchronization.

Errors

HTTP	`code`	When
503	`FEED_NOT_READY`	A complete dump cannot currently be prepared, or download capacity is temporarily exhausted. Retry with backoff; readiness has no fixed time bound.

Catalog list & search Create purchases