Skip to main content

Get catalog changes since a snapshot

GET 
/partner/catalog/delta

Returns the SKUs added, removed, or changed between since and the newest snapshot, folded across every intervening snapshot.

since must be a snapshot_id previously returned by /partner/catalog/manifest or by a prior delta's next_since. An arbitrary timestamp is rejected — the chain is snapshot-indexed and an arbitrary instant has no defined answer.

Normal loop: call with since = next_since from your last call, re-pull added + changed via POST /partner/lowest/bulk, drop removed locally, then store the new next_since.

When truncated is true, the response stops at an intermediate snapshot — it is complete and correct up to to_snapshot. Call again with since = next_since until truncated is false.

next_since always advances on a 200. It is never equal to since except in the "already up to date" case, where all three arrays are empty and truncated is false. So the loop above always terminates: it either makes progress or returns one of the 400s below.

What this endpoint does NOT report. Only SKUs the manifest marks price_source: "snapshot" are covered. SKUs marked price_source: "live" (hash: null) are never listed in changed because their price moved — we cannot fingerprint them, so we do not claim to. Their prices can and do move silently between polls. Read caveat 5 on /partner/catalog/manifest: you must refresh that cohort yourself, and the manifest identifies exactly which SKUs it contains.

now_live — cohort membership changes, and your manifest copy goes stale. A SKU is not permanently in one cohort. When its market rows stop carrying price data it crosses snapshot → live, and when a backfill reaches it it crosses back. Either crossing is reported in changed once, where it is indistinguishable from an ordinary price move — so now_live is the field that tells them apart.

now_live is a subset of added ∪ changed: it lists exactly those SKUs whose price_source is "live" as of to_snapshot. For every SKU this response names, now_live supersedes the price_source value in the manifest you downloaded:

  • in now_live → it is now live. Move it into the set you refresh on your own schedule. From here on the delta will not report its price moving; it reappears only if it crosses back or is removed.
  • named but not in now_live → it is snapshot-priced; the normal loop covers it.
  • not named at all → unchanged cohort and unchanged price if it was snapshot-priced; no statement at all if it was live.

Every delta this service writes carries now_live, so the field is always present in the response (it may be an empty array). There is no "older snapshot without the field" case to handle: the catalog store is created by the same release as the builder, so no delta object predates it. now_live cannot make this response larger than added + changed already made it.

Re-download the manifest periodically anyway — we suggest weekly, and it is the only way to re-baseline the three things the delta cannot express: product metadata (caveat 2), SKUs absent from the snapshot entirely (caveat 3), and the full membership of the live cohort (caveat 5). Do not treat a manifest you downloaded once as permanently accurate.

400 responses, and what to do about each:

  • 0011 — since missing or empty. Fix the request.
  • 0010 — since is older than the retained window, or the change chain from it is broken (a snapshot in between can no longer be diffed). There is no way to walk forward from that point. Fetch a fresh manifest.
  • 0013 — the very next snapshot's change set alone is too large to return in one response, so there is no shorter prefix to fall back to. Fetch a fresh manifest.

All three mean the same thing operationally: stop polling this since, re-download the manifest, and resume from its snapshot_id. That terminates — the manifest's snapshot_id is the newest snapshot, so your next delta call is the "already up to date" case (empty arrays, truncated: false) until the next build. If 0013 recurs, you are seeing genuinely large change sets: keep re-baselining from the manifest, which is the cheaper transfer in that situation anyway.

A 503 (0012 / 0014) means the catalog is not currently servable — see /partner/catalog/manifest. Fall back to the price endpoints.

Request​

Responses​

Changes since the given snapshot