Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.adcontextprotocol.org/llms.txt

Use this file to discover all available pages before exploring further.

The sponsored_placement canonical covers retail-media catalog-driven creative — Amazon SP, Criteo SP, CitrusAd SP, Pinterest Collection, generative-per-SKU. The schema captures the binary axes (composition_model, fanout_mode, item_production_model) but the runtime contract — fan-out semantics, catalog-asset wiring, per-adopter tracking — differs enough between adopter families that a manifest validating against sponsored_placement tells the buyer little about whether it will actually serve on a given retail-media network. This page documents the four contract families, their current experimental readiness, and the adopter-specific quirks that don’t live in the schema. The canonical stays experimental: true past 3.1 GA until at least two retail-media networks ship format_schema evidence (see canonical-formats.mdx §experimental — one field, both axes).

​
The four contract families

Familycomposition_modelfanout_modeitem_production_modelNondeterminism flagAdopters
Retail-media deterministic, buyer-uploadeddeterministicper_itembuyer_uploadedNot setAmazon SP
Retail-media network-composeddeterministicper_itemseller_pre_rendered_from_briefNot setCriteo SP, CitrusAd SP
Collection-layout per impressiondeterministic (debatable)multi_item_in_creativebuyer_uploadedNot setPinterest Collection, Snap Collection
Generative-per-SKUdeterministicper_itemagent_synthesizedsynthesis_nondeterministic: trueVendor-specific (Pencil, Persado, vertical retail-media platforms)

​
1. Retail-media deterministic, buyer-uploaded (Amazon SP)

The buyer uploads the catalog assets (product image, headline, description) via sync_creatives. The retail-media network ingests the catalog row + assets and serves them deterministically against query/category triggers — no fan-out at render time. The buyer can predict per-impression rendering.
  • Catalog-asset contract: buyer supplies one creative per catalog item; the source_catalog slot points at the buyer’s product feed; per-item assets are required.
  • Tracking: Amazon ASIN + standard retail-media event vocabulary. Per-item attribution maps to the catalog row’s identifier.
  • Adopter quirks: Amazon’s category-trigger system means the same uploaded creative may serve under different category contexts — buyers MUST treat impression-level category as untrusted-by-creative-shape; rely on Amazon’s reporting for category attribution.
  • Experimental readiness: predictable enough for sandbox and controlled-adopter use. Most predictable family; format_schema evidence from Amazon would support promotion toward non-experimental.

​
2. Retail-media network-composed (Criteo SP, CitrusAd SP)

The buyer supplies a brief + brand assets (logo, brand colors); the retail-media network composes the placement against its own catalog + design templates. The buyer cannot predict per-impression rendering at the asset-bundle level, only at the brand-direction level.
  • Catalog-asset contract: buyer supplies brief + brand assets; the source_catalog is the seller’s catalog (the retail-media network’s product index), not the buyer’s. The buyer’s product references are matched to seller-catalog rows via SKU / GTIN / category.
  • Tracking: retail-media network’s own event vocabulary; buyer attribution maps through the network’s reporting API, not direct creative events.
  • Adopter quirks: Criteo’s composition logic varies by retailer integration — the same buyer brief produces different placements on Walmart vs. Target vs. Best Buy via Criteo. Buyers MUST treat per-retailer rendering as opaque and rely on Criteo’s aggregated reporting.
  • Experimental readiness: suitable for controlled-adopter use. The composition opacity is the gap to non-experimental promotion — format_schema evidence would need to document the per-retailer variability.

​
3. Collection-layout per impression (Pinterest Collection, Snap Collection)

The buyer supplies a hero image + a collection of catalog items; the surface picks the collection layout per impression (grid, carousel, cover + reveal). composition_model: deterministic is technically true at the asset level but loose at the layout level.
  • Catalog-asset contract: buyer supplies one creative with a hero asset slot + an items array (each item: image + caption + URL). The source_catalog slot is the buyer’s curated item collection, not a full product feed.
  • Tracking: Pinterest’s collection-item events (collection_item_click, collection_close_up) plus standard impression/click. Per-item attribution available; layout-variant attribution is not exposed.
  • Adopter quirks: Snap Collection’s “cover + reveal” layout requires a specific aspect ratio and asset count combination — schema doesn’t enforce; buyers SHOULD pre-validate before sync.
  • Experimental readiness: suitable for controlled-adopter use. The “deterministic” claim survives at the asset level but layout variability blocks non-experimental promotion without per-surface conformance evidence.

​
4. Generative-per-SKU (vendor-specific)

The buyer supplies a brief + catalog reference; the seller’s generative pipeline produces a unique creative per SKU. 1 brief × N catalog items → N rendered creatives. composition_model remains deterministic because each rendered item is produced before delivery and then served as produced; the generative mechanism is captured by item_production_model: "agent_synthesized".
  • Catalog-asset contract: buyer supplies the brief + a catalog scope (SKUs, categories, or full feed); the seller produces creatives via build_creative with item_production_model: agent_synthesized and fanout_mode: per_item. The source_catalog slot is the buyer’s product feed; assets are seller-generated.
  • Nondeterminism: products in this family SHOULD declare synthesis_nondeterministic: true when generation cannot guarantee in-spec output before the QA loop completes.
  • Tracking: generative-output ID + buyer’s catalog-item key (SKU/GTIN). Buyers SHOULD treat each generated creative as a distinct rendered output with its own performance signal, not as a copy of the brief.
  • Adopter quirks: generative seeds and prompts are typically not exposed back to the buyer; buyers cannot reproduce a specific generation. Plan for re-generation cycles rather than asset-edit cycles.
  • Experimental readiness: leave experimental: true until generative-quality evidence is documented per-adopter. Controlled use is possible, but the composition is opaque to the buyer and needs per-vendor framing.

​
Experimental-readiness matrix

FamilyControlled-adopter useDefault production routingPromotion evidence
Retail-media deterministic, buyer-uploadedReadyKeep experimental until evidence landsAmazon format_schema evidence
Retail-media network-composedReadyKeep experimental until evidence landsPer-retailer variability documentation
Collection-layout per impressionReadyKeep experimental until evidence landsPer-surface conformance evidence
Generative-per-SKUVendor-specific onlyKeep experimentalGenerative-quality evidence; may not promote without per-vendor framing
experimental lives on both the canonical and the product declaration. See canonical-formats.mdx §experimental — one field, both axes for the field-level contract.

​
What this page is not

  • Not a normative spec extension. The four families share the existing sponsored_placement schema; this doc names the variability sellers and buyers will encounter against the canonical, but adds no required fields.
  • Not a promotion gate. The canonical’s promotion to non-experimental is gated on format_schema evidence across at least two adopters, per canonical-formats.mdx. This page documents what format_schema evidence will need to cover for each family.
  • Not exhaustive. Adopters whose runtime contract doesn’t fit one of the four families above SHOULD file an issue against the canonical-formats track so the matrix can be extended.

​
Refs