sync_catalogs manages buyer-provided data feeds that a seller uses to render or target ads. This is separate from the seller-side wholesale product feed exposed by get_products buying_mode: "wholesale" and the wholesale signals feed exposed by get_signals discovery_mode: "wholesale"; webhooks are the push layer for changes to those seller-side feeds.
Response Time: Instant to days (returns completed for small catalogs, or submitted for large feeds requiring platform review)
Request Schema: /schemas/3.2.0-beta.0/media-buy/sync-catalogs-request.json
Response Schema: /schemas/3.2.0-beta.0/media-buy/sync-catalogs-response.json
Who calls whom
The buyer callssync_catalogs on the seller to push catalog feeds to the seller’s account. The seller validates items, runs content policy checks, and returns per-item approval status.
This task sits between format discovery and creative submission in the account state setup sequence:
get_products— check canonicalformat_options[].params.slots[]for catalog requirementssync_catalogs— push the required feeds to the accountsync_creatives— submit creatives that reference synced catalogs bycatalog_idcreate_media_buy— launch the campaign
Quick start
Sync a product feed:Request parameters
Immediate item availability
item_availability_updates lets the buyer correct time-sensitive availability without re-sending a full feed or waiting for the next scheduled fetch. It applies only to catalogs the buyer manages on the seller account. Seller-owned wholesale inventory and seller policy removals continue to use the seller’s wholesale-feed and impairment lifecycles.
Before sending updates, check get_adcp_capabilities for:
applied or unchanged, it MUST prevent further selection or dynamic rendering, including every cached or pre-generated creative materialized from the item. Internal lineage therefore uses (resolved_account_id, catalog_id, catalog_generation, item_id); shorter keys are unsafe. Static creatives supplied or promoted without catalog lineage remain outside this automatic guarantee and use the creative lifecycle. unchanged is valid only when the requested overlay and expiry already match persisted state.
catalog_generation is an opaque seller-issued token returned on catalog results and discovery when this capability is advertised. It is stable across ordinary upserts and feed refreshes, changes after deletion and recreation, and is never reused for the same account and catalog_id. This prevents a delayed update from applying to a new catalog that reused the buyer’s ID.
item_id is the exact canonical key used by Catalog.ids: offering_id, store_id, hotel_id, flight_id, job_id, vehicle_id, listing_id, program_id, destination_id, or app_id for those typed catalogs. Product, inventory, and promotion feeds use the stable normalized source identifier retained during ingestion.
A restore removes only the buyer-authored suppression. The item remains subject to seller approval, policy, rights, inventory, and other controls. If the item is absent, restore is allowed only when a prior overlay or tombstone exists in the same catalog generation; otherwise it fails with REFERENCE_NOT_FOUND.
Each (catalog_id, catalog_generation, item_id) tuple can appear only once in the update array. A duplicate
is an operation-level INVALID_REQUEST before mutation in both validation
modes. The combined update and query count cannot exceed 1,000; buyers chunk larger workloads. Excess entries fail before lookup or mutation. For any mixed request, the seller validates and stages catalog upserts and availability updates, evaluates queries against that post-upsert/post-update candidate state, and then commits once before returning query results. If it cannot commit synchronously and atomically, it rejects before any mutation.
Suppression persists across scheduled feed fetches and ordinary catalog upserts;
only an explicit restore, the optional expires_at, or deletion of the containing catalog clears it. This
prevents the next hourly feed refresh from accidentally re-enabling an item. A
restore can clear an existing overlay while the item is temporarily absent only
when the seller retained its prior overlay or tombstone in that generation.
Availability updates are always synchronous. A seller MUST NOT return
status: "submitted" for a request containing them. If a mixed request’s catalog
upserts require async processing, the seller rejects it with INVALID_REQUEST
before mutation and the buyer sends the immediate availability update and the
catalog sync as separate calls. dry_run: true is not allowed with availability
updates because their result statuses acknowledge real persisted state, not a
preview.
Every update includes expected_overlay_revision, obtained from a current-state query. Revision 0 is the initial active state. Each applied suppress, applied restore, and automatic expiry increments it exactly once; unchanged updates, reads, and idempotent replays do not. A mismatch returns CONFLICT without mutation, so concurrent suppress/restore operations cannot overwrite one another.
validation_mode does not weaken the request envelope. Schema errors, duplicate identities, an undeclared capability, batch-limit excess, dry_run conflicts, and a mixed request that cannot commit atomically are operation-level failures before lookup or mutation in both modes. For entry failures, strict rejects the whole operation before mutation; lenient returns a failed result in its request position and processes valid entries. Unknown, inaccessible, unauthorized, and stale-generation references are observationally identical: code: "REFERENCE_NOT_FOUND", message exactly Catalog item not found, recovery correctable, and no field, suggestion, retry hint, issues, details, or resource metadata. Sellers use the same authorization/lookup failure path and avoid materially distinguishable timing. A known seller-managed catalog may return INVALID_REQUEST only after access is authorized.
Responses contain exactly one update result per update and one state result per query, in request order. Every result carries request_index and echoes the complete identity (and action for updates). Buyers reject count, order, index, or echo mismatches rather than correlating heuristically. A response with replayed: true is historical; after expiry, deletion, or uncertainty, issue a query with a fresh idempotency key before treating it as current.
The overlay applies to active packages and future item selection, but it does
not change catalog-item-status to withdrawn, pause or cancel a media buy, or
create a seller-removal impairment. The buyer intentionally requested this
state and receives its acknowledgement directly. If suppressing the last
eligible item leaves a package unable to deliver, the buyer restores or replaces
the item or controls the buy; the seller continues normal delivery and
underdelivery reporting.
out_of_stock, back_in_stock, content_unavailable, content_available, promotion_start, promotion_end, time_window_started, time_window_expired, buyer_request, and other. When using other, include reason_detail.
Price, copy, and asset changes are catalog content updates, not availability transitions; send those through the ordinary catalogs upsert path.
Catalog object
Each catalog in thecatalogs array is a Catalog object. Key fields:
Response
Success response — per-catalog results:
Each suppress request may include
expires_at. At that instant, the seller
automatically removes the buyer-authored overlay as if it received a restore.
Omit it for an indefinite suppression; it is invalid on restore requests. A
repeated suppress replaces the prior expiry: a changed timestamp, or omission
that clears a previous timestamp, returns applied. unchanged is only correct
when both the suppression state and expiry already match the request.
Error response — operation failed entirely:
Responses use discriminated unions — a synchronous success has
status: "completed", always contains catalogs (an empty array for an availability-only call), and may contain update or state results; an operation-level failure contains errors instead.
Availability update response
Availability state response
Example response with item-level review
Item review lifecycle
Catalog items follow a simple review cycle: items enterpending on sync, and the platform reviews them asynchronously. Items are either approved, rejected (with reasons), or approved with warning (serving but with fixable issues).
Rejection is not terminal — fix the issue in the source catalog and re-sync. Re-syncing an item resets it to pending for re-review. The item_issues array on the response identifies per-item rejection reasons.
Discovery mode
Omitcatalogs, item_availability_updates, and item_availability_queries to list all catalogs on the account without modification:
Async approval workflow
Large feeds or feeds requiring content policy review returnstatus: "submitted" with a task_id. The seller reviews items asynchronously and notifies the buyer via webhook when done.
Async response states:
working— platform is processing the feed (fetching URL, validating items)input-required— platform needs buyer action (fix validation errors, provide missing fields)submitted— review complete, final per-catalog results available
push_notification_config on the request to receive webhook notifications for state transitions.
Common scenarios
Retail media (product + inventory + store)
Recruitment (inline job offerings)
Dry run validation
Error handling
Best practices
- Check format requirements first — Read the selected product’s canonical declaration and inspect its catalog slots before syncing. This tells you what catalog types to sync and what fields each item needs.
-
Use discovery mode — Before syncing, call without
catalogsto see what the seller already has. The seller may have brand data from other sources. -
Set
update_frequency— For URL-based feeds, always setupdate_frequencyso the platform knows how often to re-fetch. Stale feeds lead to ads showing out-of-stock products. -
Declare
conversion_events— Connect catalogs to the conversion tracking system by declaring which event types represent conversions for catalog items. -
Use
dry_runfor large feeds — Validate before committing, especially for first-time syncs with thousands of items. -
Handle per-item failures — In
lenientmode, valid items are processed even when others fail. Checkitem_issueson the response to fix rejected items.
Next steps
- Catalogs — Complete documentation on catalog types, sourcing, and format requirements
- Account state — How catalogs fit into the account setup sequence
- sync_creatives — Submit creatives that reference synced catalogs
- Canonical formats — Discover format catalog requirements