Catalog

Overview

A catalog is an advertiser’s structured list of what it sells — products, offerings, job openings, hotels, vehicle or real-estate listings — made available to the platform as a feed. Once a catalog is synced, sellers can build ads from the actual items: a product carousel showing four of your dresses with live prices and photos, instead of one static banner. Catalog data also closes the measurement loop — conversion events reference item IDs from the catalog, so purchases attribute back to the items that were shown. You don’t build anything to have a catalog. If you run a store, you already have one — it’s your product list. Getting it onto the platform is a matter of exporting or pointing at a feed you already have.

Getting your feed

A catalog is sourced one of two ways — a remote url the platform re-fetches on a schedule, or items supplied inline in the sync request. Each catalog uses one or the other, never both. You can also upload a CSV or JSON product feed file (up to 5 MB) from the buyer Library. The upload first creates a Draft catalog. The Catalogs lens shows the parsed item count and any rows that could not be used, with a reason. Save the Draft to make it available to catalog-driven building and delivery, or Discard it to remove it. A Draft is not available to agents, building, or delivery.

Shopify store

Two options, no app required:

Product export CSV — in the Shopify admin, go to Products → Export, choose All products and CSV for Excel, Numbers, or other spreadsheet programs. Shopify emails you a download link. That CSV is a supported feed as-is with feed_format: "shopify" — the standard export columns (Handle, Title, Vendor, Variant Price, Image Src, …) parse directly. Supply the rows as inline items, or host the file at a URL.
Public JSON feed — many Shopify stores expose their products at https://your-store.com/products.json. If yours does, use that as the feed url; a JSON feed with a top-level products array parses natively.

If you already run a feed app (for example the Google & YouTube sales channel), you can reuse the URL it generates — but note those apps emit Google Merchant Center format, so set feed_format: "google_merchant_center", not "shopify".

Google Merchant Center

Point the feed url at your existing Merchant Center feed (XML or CSV) with feed_format: "google_merchant_center".

Meta / Facebook catalog

Reuse your Facebook catalog feed URL with feed_format: "facebook_catalog".

Job feeds

LinkedIn Jobs XML feeds are supported with feed_format: "linkedin_jobs" and type: "job".

Anything else

feed_format: "custom" accepts JSON, XML, or CSV. Non-standard field names can be normalized with feed field mappings.

Key fields

Field	Type	Notes
`catalog_id`	string	Your identifier for the catalog — creatives and campaigns reference it
`type`	enum	What the items are: `product`, `offering`, `job`, `hotel`, `flight`, `vehicle`, `real_estate`, `education`, `destination`, and more
`url`	string	Remote feed URL — provide this or `items`
`items`	array	Inline feed rows (max 10,000) — provide this or `url`
`feed_format`	enum	`shopify`, `google_merchant_center`, `facebook_catalog`, `linkedin_jobs`, `custom`
`update_frequency`	enum	How often a URL feed is re-fetched: `realtime`, `hourly`, `daily`, `weekly`
`conversion_events`	array	Event types (e.g. `purchase`, `add_to_cart`) attributed to items in this catalog

Lifecycle

Sync — push the catalog with Sync catalogs. Up to 50 catalogs per call; the response reports per-catalog action (created / updated / unchanged) and per-item review counts.
Review — items are validated and content-reviewed. Rejections come back in item_issues with a field-level reason (for example an unreachable image URL), so you can fix the feed and re-sync. A file upload remains a Draft at this step until a person saves it in the buyer Library.
Use — campaigns and creatives reference the catalog by catalog_id; catalog-driven formats render items dynamically.
Refresh — URL feeds re-fetch on their update_frequency; Refresh catalog re-fetches on demand and creates a new version when the data changed.

Beyond referencing items in creatives, a catalog can drive campaign creation itself: catalog activation fans items out into campaign groups, budget hints, and creative prompts via a saved transform. See Save catalog transform for the transform → preview → execute → refresh flow. The whole flow is also available in the UI under Data sources → Catalogs.

V3 catalog tools

Buyer agents can use save_catalog to create, replace, or archive one catalog. The same declaration is available through search(kind: "catalog") and get(kind: "catalog", id, advertiserId: "12345"). A get request can include a bounded page of items with include: ["items"]; item filters support item IDs, product GTINs, tags, category, and text (text contained anywhere in an item). Item IDs are the AdCP key for the catalog type: offering_id, store_id, hotel_id, flight_id, job_id, vehicle_id, listing_id (real estate), program_id (education), destination_id, or app_id; product, inventory, and promotion catalogs use the item’s source identifier, such as its SKU. Items read back exactly as saved. There is no item review status filter yet: review results arrive from sellers once catalogs are forwarded to them. Use the returned cursor for another page rather than requesting an unbounded feed. Inline items must match the AdCP item schema for the catalog type, so a hotel item needs hotel_id, name, and location, and a job item needs job_id, title, company_name, and description. Product, inventory, and promotion items are not checked against a type schema. A catalog reads back with the same flat fields save_catalog takes: the feed source (url, feedFormat, updateFrequency, feedFieldMappings) and the selection filters (ids, gtins, tags, category, query) sit at the top level, not in a wrapper. Each feedFieldMappings entry is an AdCP CatalogFieldMapping: exactly one of feed_field or a static value, exactly one of catalog_field or asset_group_id, and the optional transform with its format, timezone, by (above zero), and separator. For example, { "feed_field": "price_cents", "catalog_field": "price.amount", "transform": "divide", "by": 100 }. save_catalog requires an idempotency key. A repeated completed request with the same key returns its original result for 24 hours, so a retry does not create another catalog update. URL catalogs are fetched again when saved; archive a catalog with isArchived: true and the same catalogId and advertiserId instead of using a separate delete tool. The MCP request is the catalog object itself — do not wrap it in catalog: Draft catalogs are intentionally excluded from normal agent reads. An agent may list Draft catalog summaries only with the explicit search(kind: "catalog", filter: { catalogState: "draft", advertiserId: "..." }) filter; it cannot get their rows or use them in a build or delivery until a person saves the Draft.

{
  "catalogId": "summer-sale-2026",
  "advertiserId": "12345",
  "name": "Summer Sale 2026",
  "type": "product",
  "url": "https://feeds.acme.com/products.xml",
  "feedFormat": "google_merchant_center",
  "updateFrequency": "daily",
  "idempotencyKey": "save-summer-sale-2026-0001"
}

Buy Spotify podcast promotion with a catalog

A Spotify podcast promotion promotes one show. Name the show in an offering catalog, attach the catalog to the campaign, and Apostra sends the catalog with the buy. The catalog carries one item, with offering_id set to the show’s 22-character Spotify id and landing_url set to its https://open.spotify.com/show/<id> link:

{
  "catalogId": "my-podcast",
  "advertiserId": "12345",
  "name": "My Podcast",
  "type": "offering",
  "items": [
    {
      "offering_id": "6fS5boWGwYTShddG7SKlVw",
      "name": "My Podcast",
      "landing_url": "https://open.spotify.com/show/6fS5boWGwYTShddG7SKlVw"
    }
  ],
  "idempotencyKey": "save-my-podcast-0001"
}

Then call save_campaign with catalogId: "my-podcast" and book the Spotify podcast promotion product (spotify_engagement_streams_promotion) on the campaign. The catalog goes only to products that list offering in their catalog_types; a campaign whose media buys include a product that does not list it still cannot launch with a catalog (SELLER_CATALOG_SYNC_UNAVAILABLE). On Spotify the catalog names the show; it does not split the budget into one ad set per item, as an offering catalog does on other platforms. Spotify refuses a catalog that names no show, an item that is not a Spotify show, and a catalog that names more than one show; the buy is refused before anything is created at Spotify. A buy that sets ext.promotion_target_id to the show keeps working and takes precedence over the catalog.

Sync catalogs

Push catalog feeds and items to an advertiser

List catalogs

See synced catalogs and their status

Save catalog transform

Fan catalog items out into campaigns

Glossary

Catalog and catalog activation, defined

Start here

Buy media

Sell media

Help and updates

Overview

Getting your feed

Key fields

Lifecycle

V3 catalog tools

Buy Spotify podcast promotion with a catalog

Sync catalogs

List catalogs

Save catalog transform

Glossary

​Overview

​Getting your feed

​Key fields

​Lifecycle

​V3 catalog tools

​Buy Spotify podcast promotion with a catalog

​Related

Sync catalogs

List catalogs

Save catalog transform

Glossary

Overview

Getting your feed

Key fields

Lifecycle

V3 catalog tools

Buy Spotify podcast promotion with a catalog

Related