AdCP list_products Task

list_products is the side-effect-free entry point to the compact product lifecycle. Each invocation completes synchronously, while account-level wholesale feed webhooks keep long-lived buyer mirrors current without polling. It returns products only—never proposals. Buyers can purchase listed products through buy_products or pass returned product_id values to request_proposals for seller planning. Request schema: /schemas/3.0.23/media-buy/list-products-request.json

{
  "brand": { "domain": "acmeoutdoor.example" },
  "criteria": {
    "offer_filters": {
      "channels": ["olv"],
      "pricing_currencies": ["USD"]
    },
    "targeting_overlay": {
      "geo_countries": ["US"]
    },
    "required_overlay_support": {
      "geo_metros": { "systems": ["nielsen_dma"] }
    }
  },
  "max_results": 25
}

brand is an identity-only key. Sellers resolve its canonical manifest from the domain; callers do not send logos, colors, or governance overrides in this request. Catalog ingestion belongs to sync_catalogs; discovery accepts only a compact catalog selection under criteria.catalog. offer_filters select commercial offers. targeting_overlay instead constrains the inventory or impressions that may deliver, so every returned price and forecast must account for the effective overlay. required_overlay_support asks for targeting dimensions the buyer can select independently on packages later; it does not request one product per metro or guarantee availability for every future value. When a product can honor the overlay exactly, it does not echo the request. A product that proposes a different executable overlay returns sparse targeting_resolution.modifications; selecting that configured product accepts those disclosed changes.

Response

Every response has an explicit outcome:

Field	Type	Description
`outcome`	string	`listed` when the response contains a product page; `unchanged` when a conditional request matches the current feed.
`products`	Product[]	Product offers for this page. Required for `listed`, even when the array is empty; omitted for `unchanged`.
`next_cursor`	string	Cursor for the next page. Omitted on the final page. Pass it as `cursor` in the next request.
`feed_version`	string	Opaque version of the selected offer feed. Pass it as `if_feed_version` on a later request to avoid downloading an unchanged feed.
`pricing_version`	string	Opaque version of the selected pricing layer. Pass it as `if_pricing_version` together with `if_feed_version` when checking both versions.
`cache_scope`	string	Whether the version applies to the seller’s `public` feed or an `account`-specific overlay.
`incomplete`	object[]	Optional details about portions of the response the seller could not complete.

A product page can include continuation and cache state:

{
  "outcome": "listed",
  "products": [],
  "next_cursor": "page_2",
  "feed_version": "feed_2026_08_10_1",
  "pricing_version": "pricing_42",
  "cache_scope": "account"
}

To check whether the same selection has changed, repeat the request with if_feed_version. Include if_pricing_version only when if_feed_version is also present:

{
  "brand": { "domain": "acmeoutdoor.example" },
  "criteria": {
    "offer_filters": {
      "channels": ["olv"],
      "pricing_currencies": ["USD"]
    },
    "targeting_overlay": {
      "geo_countries": ["US"]
    }
  },
  "if_feed_version": "feed_2026_08_10_1",
  "if_pricing_version": "pricing_42"
}

If the selected feed and pricing layer still match, the seller can omit products:

{
  "outcome": "unchanged",
  "feed_version": "feed_2026_08_10_1",
  "pricing_version": "pricing_42",
  "cache_scope": "account"
}

Wholesale feed webhooks

Buyers maintaining a wholesale product mirror register product.* and wholesale_feed.bulk_change subscribers through sync_accounts.accounts[].notification_configs[]. Registration is account-level and durable; push_notification_config on an individual list_products request does not create that subscription. The normal mirror flow is:

Call list_products to bootstrap the mirror and store feed_version plus cache_scope.
Register the durable account subscriber through sync_accounts.
Apply the webhook’s canonical_product or canonical_pricing_options replacement payload directly.
On a gap, call list_products with the mirror’s last successfully applied feed_version. On an uncertain or bulk-change repair, omit the conditional token and replace the mirror from a complete read.

The webhook version describes post-change state; it is not the conditional token for a stale mirror. Conditional reads are a repair path, not a requirement to poll while webhooks are healthy.

Getting Started

Building with AdCP

Protocol

Using AAO

FAQ

Trust & Security

Reference

Certification

list_products

Response

Wholesale feed webhooks

​Response

​Wholesale feed webhooks

Response

Wholesale feed webhooks