AdCP — Media Products

A Product is the core sellable unit in AdCP. This document details the Product model, including its pricing and delivery types, and how products are discovered and structured in the system.

Pricing Models Products declare which pricing models they support. Buyers select a specific pricing option when creating media buys. See the complete Pricing Models Guide for details on CPM, CPCV, CPP, CPC, CPA, vCPM, flat rate, and time-based pricing.

The Product Model

product_id (string, required)
name (string, required)
description (string, required)
publisher_properties (list[PublisherPropertySelector], required): Publisher properties covered by this product. See Property Targeting.
channels (list[string], optional): Advertising channels this product is sold as (e.g., ["retail_media"], ["display", "olv"]). Sellers SHOULD declare channels on products that span non-obvious channels, particularly retail media, CTV/OLV, and multi-channel bundles. Product channels SHOULD be a subset of the union of their properties’ supported_channels. See Media Channel Taxonomy.
format_ids (list[FormatID], required): Structured format ID references. See Creative Formats.
placements (list[Placement], optional): Specific ad placements within this product. When provided, buyers can target individual placements when assigning creatives. See Placements.
show_ids (list[string], optional): Show IDs available within this product. When provided, buyers can target specific shows. See Shows and episodes.
episodes (list[Episode], optional): Specific episodes available within this product. See Shows and episodes.
delivery_type (string, required): Either "guaranteed" or "non_guaranteed".
exclusivity (string, optional): Whether this product offers exclusive access. "none" (default when absent) — multiple advertisers can buy simultaneously. "category" — one advertiser per industry category. "exclusive" — sole sponsorship. Most relevant for guaranteed products tied to specific shows or placements.
pricing_options (list[PricingOption], required): Array of available pricing models for this product. See Pricing Models.
delivery_measurement (object, optional): Who measures ad delivery — the ad server and viewability vendor used to count impressions (e.g., “Google Ad Manager with IAS viewability”). When absent, buyers should apply their own measurement defaults. See Delivery Measurement.
outcome_measurement (OutcomeMeasurement, optional): Business outcome measurement included with the product — incremental sales lift, brand lift studies, etc. Common for retail media products.
creative_policy (CreativePolicy, optional): Creative requirements and restrictions.
is_custom (bool, optional): true if the product was generated for a specific brief.
expires_at (datetime, optional): If is_custom, the time the product is no longer valid.
property_targeting_allowed (bool, optional, default: false): Whether buyers can filter this product to a subset of its publisher_properties. When false (default), the product is “all or nothing” - buyers must accept all properties or the product is excluded from property_list filtering results. See Property Targeting.
catalog_types (list[string], optional): Catalog types this product supports for catalog-driven campaigns. A sponsored product listing declares ["product"], a job board declares ["job", "offering"]. Buyers match synced catalogs to products via this field. See Catalogs.
catalog_match (object, optional): When the buyer provides a catalog on get_products, indicates which catalog items are eligible for this product. Contains matched_gtins (cross-retailer GTIN matches), matched_ids (generic item ID matches), matched_count, and submitted_count.
metric_optimization (object, optional): Metric optimization capabilities for this product. Presence indicates the product supports optimization_goals with kind: "metric". See Metric optimization.
max_optimization_goals (integer, optional): Maximum number of optimization_goals this product accepts on a package. When absent, no limit is declared. Most social platforms accept only 1.
conversion_tracking (object, optional): Conversion event tracking capabilities. Presence indicates the product supports optimization_goals with kind: "event". See Conversion tracking.
product_card (object, optional): Visual card definition for displaying this product in user interfaces. See Product Cards.

Metric optimization

Products that support optimization_goals with kind: "metric" declare their capabilities in metric_optimization. No event source or conversion tracking setup is required for metric goals — the seller tracks these metrics natively.

{
  "metric_optimization": {
    "supported_metrics": ["clicks", "views", "completed_views", "engagements"],
    "supported_view_durations": [2, 6, 15],
    "supported_targets": ["cost_per", "threshold_rate"]
  }
}

Field	Type	Required	Description
`supported_metrics`	string[]	Yes	Metric kinds this product can optimize for. Buyers should only request metric goals for kinds listed here.
`supported_view_durations`	number[]	No	Video view duration thresholds (in seconds) supported for `completed_views` goals. When absent, the seller uses their platform default.
`supported_targets`	string[]	No	Target kinds available: `cost_per`, `threshold_rate`. Values match `target.kind` on the optimization goal. Only listed kinds are accepted. When omitted, buyers can set target-less metric goals (maximize volume) but cannot set specific targets.

Conversion tracking

Products that support optimization_goals with kind: "event" declare their capabilities in conversion_tracking. Seller-level capabilities (supported event types, UID types, attribution windows) are declared in get_adcp_capabilities.

{
  "conversion_tracking": {
    "action_sources": ["website", "app"],
    "supported_targets": ["cost_per", "per_ad_spend", "maximize_value"],
    "platform_managed": false
  }
}

Field	Type	Required	Description
`action_sources`	string[]	No	Action sources relevant to this product (e.g., a retail media product might have `in_store` and `website`).
`supported_targets`	string[]	No	Target kinds available for event goals: `cost_per`, `per_ad_spend`, `maximize_value`. Values match `target.kind` on the optimization goal. Only listed kinds are accepted. When omitted, buyers can still set target-less event goals.
`platform_managed`	boolean	No	Whether the seller provides always-on measurement (e.g., retailer purchase attribution). When true, `sync_event_sources` returns seller-managed event sources.

See Conversion Tracking & Optimization Goals for the full optimization goals reference.

Pricing Models

Publishers declare which pricing models they support for each product. Buyers select from the available options when creating a media buy. This approach supports:

Multiple pricing models per product - Publishers can offer the same inventory via different pricing structures
Multi-currency support - Publishers declare supported currencies; buyers must use a supported currency
Flexible pricing - Support for CPM, CPCV, CPP (GRP-based), CPA, and more

Supported Pricing Models

CPM (Cost Per Mille) - Cost per 1,000 impressions (traditional display)
CPC (Cost Per Click) - Cost per click on the ad
CPCV (Cost Per Completed View) - Cost per 100% video/audio completion
CPV (Cost Per View) - Cost per view at publisher-defined threshold
CPA (Cost Per Acquisition) - Cost per conversion event (purchase, lead, signup, etc.)
CPP (Cost Per Point) - Cost per Gross Rating Point (TV/audio)
Flat Rate - Fixed cost regardless of delivery volume
Time - Cost per time unit (day, week, month) that scales with campaign duration

PricingOption Structure

Each pricing option includes:

{
  "$schema": "https://adcontextprotocol.org/schemas/v3/pricing-options/cpcv-option.json",
  "pricing_option_id": "cpcv_usd_guaranteed",
  "pricing_model": "cpcv",
  "fixed_price": 0.15,
  "currency": "USD",
  "min_spend_per_package": 5000
}

For auction-based pricing (no fixed_price), use floor_price for minimum bid constraints and optional price_guidance for percentile hints. Bid-based auction models (cpm, vcpm, cpc, cpcv, cpv) may also include max_bid as a boolean signal that bid_price switches from exact honored price to buyer ceiling mode:

{
  "$schema": "https://adcontextprotocol.org/schemas/v3/pricing-options/cpm-option.json",
  "pricing_option_id": "cpm_usd_auction",
  "pricing_model": "cpm",
  "currency": "USD",
  "floor_price": 10.00,
  "max_bid": true,
  "price_guidance": {
    "p25": 12.50,
    "p50": 15.00,
    "p75": 18.00,
    "p90": 22.00
  }
}

Delivery Measurement

Products SHOULD declare their measurement provider when available:

{
  "delivery_measurement": {
    "provider": "Google Ad Manager with IAS viewability verification",
    "notes": "MRC-accredited viewability. 50% in-view for 1s display / 2s video."
  }
}

Common provider examples:

"Google Ad Manager with IAS viewability"
"Nielsen DAR for P18-49 demographic measurement"
"Geopath DOOH traffic counts updated monthly"
"Comscore vCE for video completion tracking"
"Self-reported impressions from proprietary ad server"

Outcome Measurement Object

For products that include outcome measurement (common in retail media):

{
  "type": "incremental_sales_lift",
  "attribution": "deterministic_purchase",
  "window": { "interval": 30, "unit": "days" },
  "reporting": "weekly_dashboard"
}

CreativePolicy Object

Defines creative requirements and restrictions:

{
  "$schema": "https://adcontextprotocol.org/schemas/v2/core/creative-policy.json",
  "co_branding": "required",
  "landing_page": "retailer_site_only",
  "templates_available": true
}

Placements

Products can optionally declare specific ad placements within their inventory. When placements are provided:

Buyers purchase the entire product - Packages always target the whole product, not individual placements
Placement targeting happens at creative assignment - Different creatives can be assigned to different placements
Omitting placement targeting - Creatives without placement_ids run on all placements in the package

Placement Object Structure

{
  "$schema": "https://adcontextprotocol.org/schemas/v2/core/placement.json",
  "placement_id": "homepage_banner",
  "name": "Homepage Banner",
  "description": "Above-the-fold banner on the homepage",
  "format_ids": [
    {"agent_url": "https://creative.adcontextprotocol.org", "id": "display_728x90"},
    {"agent_url": "https://creative.adcontextprotocol.org", "id": "display_970x250"}
  ]
}

Example: Product with Placements

{
  "product_id": "news_site_premium",
  "name": "News Site Premium Package",
  "description": "Premium placements across news site",
  "format_ids": [
    {"agent_url": "https://creative.adcontextprotocol.org", "id": "display_728x90"},
    {"agent_url": "https://creative.adcontextprotocol.org", "id": "display_300x250"}
  ],
  "placements": [
    {
      "placement_id": "homepage_banner",
      "name": "Homepage Banner",
      "format_ids": [{"agent_url": "https://creative.adcontextprotocol.org", "id": "display_728x90"}]
    },
    {
      "placement_id": "article_sidebar",
      "name": "Article Sidebar",
      "format_ids": [{"agent_url": "https://creative.adcontextprotocol.org", "id": "display_300x250"}]
    }
  ],
  "delivery_type": "guaranteed",
  "pricing_options": [...]
}

When creating a media buy, buyers can assign different creatives to different placements:

{
  "packages": [
    {
      "product_id": "news_site_premium",
      "creative_assignments": [
        {
          "creative_id": "creative_1",
          "placement_ids": ["homepage_banner"]
        },
        {
          "creative_id": "creative_2",
          "placement_ids": ["article_sidebar"]
        }
      ]
    }
  ]
}

See Creative Assignment and Placement Targeting for more details.

Shows and episodes

Shows are a third product dimension alongside formats and placements. While placements describe where an ad appears and formats describe what the ad looks like, shows describe the content context — the programming a viewer is watching. Products can declare show_ids and episodes so buyers can target specific shows or episodes when purchasing inventory. See Shows and episodes for the full model, examples, and targeting details.

Exclusivity

The exclusivity field indicates whether a product offers exclusive access to its inventory. Defaults to "none" when absent.

Value	Meaning
`none`	Multiple advertisers can buy this product simultaneously
`category`	One advertiser per industry category (e.g., one auto brand per show sponsorship)
`exclusive`	Sole sponsorship — only one advertiser can buy this product

Exclusivity is most relevant for guaranteed products tied to specific shows or placements, where advertisers want brand separation or sole ownership of a content association.

When to use each level

none: Programmatic inventory, run-of-network, open auction products. Multiple advertisers sharing the same inventory is expected.
category: Podcast or CTV sponsorships where competitive separation matters. One auto brand per show, one fintech brand per episode — but multiple non-competing advertisers can buy simultaneously.
exclusive: Sole sponsorship of a single show or event. The advertiser is the only brand associated with the content.

Publishers SHOULD include exclusivity on guaranteed products with show_ids. The implicit default of "none" is ambiguous for show-level inventory — buyers cannot tell whether the publisher intends shared inventory or simply omitted the field.

Content sponsorship pattern

A product combining delivery_type: "guaranteed", exclusivity: "exclusive", and show_ids represents a content sponsorship — the advertiser becomes the sole sponsor of specific content. This is the standard pattern for podcast title sponsorships, CTV show sponsorships, and event-based takeovers.

{
  "product_id": "signal_noise_sponsor",
  "name": "Signal & Noise — Exclusive Sponsorship",
  "description": "Sole sponsorship of Signal & Noise, a weekly technology podcast. Includes pre-roll and mid-roll placements across all episodes.",
  "publisher_properties": [
    { "publisher_domain": "crestnetwork.example", "property_ids": ["crest_podcasts"] }
  ],
  "format_ids": [
    { "agent_url": "https://ads.crestnetwork.example", "id": "audio_pre_roll_30s" },
    { "agent_url": "https://ads.crestnetwork.example", "id": "audio_mid_roll_60s" }
  ],
  "show_ids": ["signal_noise"],
  "delivery_type": "guaranteed",
  "exclusivity": "exclusive",
  "pricing_options": [
    {
      "pricing_option_id": "flat_monthly",
      "pricing_model": "flat_rate",
      "fixed_price": 25000,
      "currency": "USD"
    }
  ]
}

Category exclusivity works for multi-show bundles where the publisher separates competing brands across a network but still sells to multiple non-competing advertisers:

{
  "product_id": "crest_business_bundle",
  "name": "Crest Business Podcast Bundle — Category Sponsorship",
  "description": "Sponsorship across three business podcasts. One advertiser per industry category across all shows.",
  "publisher_properties": [
    { "publisher_domain": "crestnetwork.example", "property_ids": ["crest_podcasts"] }
  ],
  "format_ids": [
    { "agent_url": "https://ads.crestnetwork.example", "id": "audio_pre_roll_30s" },
    { "agent_url": "https://ads.crestnetwork.example", "id": "audio_mid_roll_60s" }
  ],
  "show_ids": ["signal_noise", "market_beat", "founder_stories"],
  "delivery_type": "guaranteed",
  "exclusivity": "category",
  "pricing_options": [
    {
      "pricing_option_id": "flat_quarterly",
      "pricing_model": "flat_rate",
      "fixed_price": 60000,
      "currency": "USD"
    }
  ]
}

Property Targeting

The property_targeting_allowed flag indicates whether buyers can filter a product to a subset of its publisher_properties when using property list filtering via get_products.

Behavior

property_targeting_allowed: false (default): The product is “all or nothing.” If the buyer’s property_list doesn’t include all of the product’s properties, the product is excluded from results entirely.
property_targeting_allowed: true: Buyers can filter the product to properties matching their property_list. The product is included in results if there is any intersection between its properties and the buyer’s list.

Use Cases

Use Case	`property_targeting_allowed`	Why
Run of Network	`false`	Buyers must accept the entire network
Premium Bundles	`false`	Sports + News bundle sold together
Flexible Inventory	`true`	Buyers can target specific sites within a category

Examples

All-or-nothing product (property_targeting_allowed: false):

{
  "product_id": "premium_news_bundle",
  "name": "Premium News Bundle",
  "publisher_properties": [
    { "publisher_domain": "news.example.com", "property_ids": ["site_a", "site_b", "site_c"] }
  ],
  "property_targeting_allowed": false
}

When a buyer calls get_products with a property_list containing only site_a and site_b, this product is excluded because the buyer’s list doesn’t include all properties (site_c is missing). Flexible product (property_targeting_allowed: true):

{
  "product_id": "news_category_flexible",
  "name": "News Category - Flexible Targeting",
  "publisher_properties": [
    { "publisher_domain": "news.example.com", "property_ids": ["tech", "sports", "finance", "politics"] }
  ],
  "property_targeting_allowed": true
}

When a buyer calls get_products with a property_list containing only tech and sports, this product is included because there is an intersection. The buyer can then purchase this product and target only the matching properties via targeting_overlay.property_list in the package.

Custom & Principal-Specific Products

A server can offer a general catalog, but it can also return:

Principal-Specific Products: Products reserved for or negotiated with specific clients
Custom Products: Dynamically generated products with is_custom: true and an expires_at timestamp

Product Examples

Standard CTV Product (Multiple Pricing Options)

{
  "product_id": "connected_tv_prime",
  "name": "Connected TV - Prime Time",
  "description": "Premium CTV inventory 8PM-11PM",
  "publisher_properties": [
    { "publisher_domain": "streaming.example.com", "selection_type": "all" }
  ],
  "format_ids": [
    {
      "agent_url": "https://creative.adcontextprotocol.org",
      "id": "video_15s"
    },
    {
      "agent_url": "https://creative.adcontextprotocol.org",
      "id": "video_30s"
    }
  ],
  "delivery_type": "guaranteed",
  "pricing_options": [
    {
      "pricing_option_id": "cpm_usd_guaranteed",
      "pricing_model": "cpm",
      "fixed_price": 45.00,
      "currency": "USD",
      "min_spend_per_package": 10000
    },
    {
      "pricing_option_id": "cpcv_usd_guaranteed",
      "pricing_model": "cpcv",
      "fixed_price": 0.18,
      "currency": "USD",
      "min_spend_per_package": 10000
    },
    {
      "pricing_option_id": "cpp_usd_p18-49",
      "pricing_model": "cpp",
      "fixed_price": 250.00,
      "currency": "USD",
      "parameters": {
        "demographic": "P18-49",
        "min_points": 50
      },
      "min_spend_per_package": 12500
    }
  ],
  "delivery_measurement": {
    "provider": "Nielsen DAR for P18-49 demographic measurement",
    "notes": "Panel-based measurement for GRP delivery. Impressions measured via Comscore vCE."
  }
}

Auction-Based Display Product

{
  "product_id": "custom_abc123",
  "name": "Custom - Gaming Enthusiasts",
  "description": "Custom audience package for gaming campaign",
  "publisher_properties": [
    { "publisher_domain": "gaming.example.com", "selection_type": "all" }
  ],
  "format_ids": [
    {
      "agent_url": "https://creative.adcontextprotocol.org",
      "id": "display_300x250"
    },
    {
      "agent_url": "https://creative.adcontextprotocol.org",
      "id": "display_728x90"
    }
  ],
  "delivery_type": "non_guaranteed",
  "pricing_options": [
    {
      "pricing_option_id": "cpm_usd_auction",
      "pricing_model": "cpm",
      "currency": "USD",
      "floor_price": 5.00,
      "price_guidance": {
        "p50": 8.00,
        "p75": 12.00
      }
    },
    {
      "pricing_option_id": "cpc_usd_auction",
      "pricing_model": "cpc",
      "currency": "USD",
      "floor_price": 0.50,
      "price_guidance": {
        "p50": 1.20,
        "p75": 2.00
      }
    }
  ],
  "delivery_measurement": {
    "provider": "Google Ad Manager with IAS viewability",
    "notes": "MRC-accredited viewability. 50% in-view for 1s display."
  },
  "is_custom": true,
  "expires_at": "2025-02-15T00:00:00Z"
}

Retail Media Product with Measurement

{
  "product_id": "albertsons_pet_category_offsite",
  "name": "Pet Category Shoppers - Offsite Display & Video",
  "description": "Target Albertsons shoppers who have purchased pet products in the last 90 days. Reach them across premium display and video inventory.",
  "publisher_properties": [
    { "publisher_domain": "groceryretail.example.com", "selection_type": "all" }
  ],
  "format_ids": [
    {
      "agent_url": "https://creative.adcontextprotocol.org",
      "id": "display_300x250"
    },
    {
      "agent_url": "https://creative.adcontextprotocol.org",
      "id": "display_728x90"
    },
    {
      "agent_url": "https://creative.adcontextprotocol.org",
      "id": "video_15s"
    }
  ],
  "delivery_type": "guaranteed",
  "pricing_options": [
    {
      "pricing_option_id": "cpm_usd_guaranteed",
      "pricing_model": "cpm",
      "fixed_price": 13.50,
      "currency": "USD",
      "min_spend_per_package": 10000
    }
  ],
  "delivery_measurement": {
    "provider": "Self-reported impressions from proprietary ad server",
    "notes": "Impressions counted per IAB guidelines. Viewability measured via IAS."
  },
  "outcome_measurement": {
    "type": "incremental_sales_lift",
    "attribution": "deterministic_purchase",
    "window": { "interval": 30, "unit": "days" },
    "reporting": "weekly_dashboard"
  },
  "creative_policy": {
    "co_branding": "optional",
    "landing_page": "must_include_retailer",
    "templates_available": true
  }
}

Product Cards

Product cards provide visual representations of products for display in user interfaces. Publishers can optionally include card definitions that reference card formats and provide the assets needed to render attractive visual cards.

Card Types

Publishers should provide at least the standard card, and optionally a detailed card: Standard Card (product_card):

Compact 300x400px card for product grids and lists
Supports 2x density images for retina displays
Quick visual identification of products

Detailed Card (product_card_detailed, optional):

Responsive layout with text description alongside hero carousel
Markdown specifications section below
Full product documentation similar to media kits

Structure

{
  "product_id": "ctv_premium",
  "name": "Premium CTV Inventory",
  // ... other product fields ...

  "product_card": {
    "format_id": {
      "agent_url": "https://creative.adcontextprotocol.org",
      "id": "product_card_standard"
    },
    "manifest": {
      "display_name": "Premium CTV - Living Room Audiences",
      "hero_image_url": "https://cdn.example.com/products/ctv_hero.jpg",
      "brief_highlight": "Perfect for reaching cord-cutters and premium streaming audiences"
    }
  },

  "product_card_detailed": {
    "format_id": {
      "agent_url": "https://creative.adcontextprotocol.org",
      "id": "product_card_detailed"
    },
    "manifest": {
      "display_name": "Premium CTV - Living Room Audiences",
      "description": "Reach high-income households with premium CTV inventory during peak viewing hours...",
      "carousel_images": [
        "https://cdn.example.com/products/ctv_context1.jpg",
        "https://cdn.example.com/products/ctv_context2.jpg"
      ],
      "specifications_markdown": "# Technical Specifications\n\n..."
    }
  }
}

Rendering Cards

Cards can be rendered in two ways:

Via preview_creative: Pass the card format and manifest to generate a rendered card
Pre-rendered: Publishers can pre-generate cards and serve them directly

This flexibility allows publishers to choose between dynamic generation or static hosting based on their infrastructure.

Standard Card Formats

The AdCP reference creative agent defines two standard card formats:

product_card_standard (300x400px) - Compact card for product browsing
product_card_detailed (responsive) - Rich card with carousel and full specs

Publishers can also define custom card formats to match their branding or highlight unique product attributes. Note: Standard card format definitions are maintained in the creative-agent repository, not in this protocol specification.

When to Include Product Cards

Product cards are optional but recommended for:

Products with strong visual identity (e.g., specific shows, events, publications)
Premium products where visual presentation enhances perceived value
Complex products where visual highlights help explain capabilities
Products targeting specific audiences that benefit from visual representation

Use the detailed card variant when you want to provide comprehensive product documentation similar to media kit pages.

Client Rendering Guidelines

When displaying products in UIs, clients should follow this fallback order:

If product_card exists → Render card via preview_creative or display pre-rendered image
If neither exists → Render text-only representation (product name + description)
If card rendering fails → Gracefully fall back to text-only representation

This ensures a consistent user experience regardless of what product metadata is available.

Proposals

Publishers can return proposals alongside products - structured media plans with budget allocations that buyers can execute directly.

What Are Proposals?

A proposal is a recommended buying strategy that groups products with suggested budget allocations. Proposals encode publisher expertise - the kind of media planning guidance that traditionally required human sales reps. Key characteristics:

Actionable: Buyers execute proposals directly via create_media_buy with a proposal_id
Budget-agnostic: Allocations use percentages, allowing the same proposal to scale to any budget
Forecast-equipped: Proposals and allocations can include delivery forecasts to help buyers evaluate expected performance before purchase

Proposal Structure

{
  "proposal_id": "swiss_balanced_v1",
  "name": "Swiss Multi-Channel Plan",
  "description": "Balanced coverage across devices and language regions",
  "allocations": [
    {
      "product_id": "ch_desktop_de",
      "allocation_percentage": 20,
      "pricing_option_id": "cpm_usd_fixed",
      "rationale": "Primary desktop audience in German Switzerland",
      "tags": ["desktop", "german"]
    },
    {
      "product_id": "ch_desktop_fr",
      "allocation_percentage": 30,
      "tags": ["desktop", "french"]
    },
    {
      "product_id": "ch_mobile_de",
      "allocation_percentage": 8,
      "tags": ["mobile", "german"]
    },
    {
      "product_id": "ch_mobile_fr",
      "allocation_percentage": 12,
      "tags": ["mobile", "french"]
    },
    {
      "product_id": "ch_inapp_de",
      "allocation_percentage": 12,
      "tags": ["in-app", "german"]
    },
    {
      "product_id": "ch_inapp_fr",
      "allocation_percentage": 18,
      "tags": ["in-app", "french"]
    }
  ],
  "total_budget_guidance": {
    "min": 30000,
    "recommended": 50000,
    "currency": "USD"
  },
  "brief_alignment": "Achieves 50/20/30 channel split (desktop/mobile/in-app) and 40/60 language split (German/French)",
  "forecast": {
    "points": [
      {
        "budget": 50000,
        "metrics": {
          "impressions": { "low": 800000, "mid": 1200000, "high": 1500000 },
          "reach": { "low": 400000, "mid": 600000, "high": 750000 },
          "clicks": { "mid": 4800 }
        }
      }
    ],
    "method": "modeled",
    "currency": "USD",
    "valid_until": "2025-04-15T00:00:00Z"
  }
}

The tags field enables grouping allocations by dimension:

By channel: desktop (50%) + mobile (20%) + in-app (30%) = 100%
By language: German (40%) + French (60%) = 100%

Iterating on Proposals

Proposals can be refined using buying_mode: "refine" with the refine array. Reference proposals by ID — the seller returns an updated proposal with revised allocations, forecasts, and pricing:

// Initial discovery
get_products({
  buying_mode: "brief",
  brief: "Swiss campaign, $50k, 50% desktop/20% mobile/30% in-app, 40% German/60% French"
})

// Response includes proposal "swiss_balanced_v1"

// Refine the proposal
get_products({
  buying_mode: "refine",
  refine: [
    { scope: "product", id: "ch_desktop_de", action: "include" },
    { scope: "product", id: "ch_desktop_fr", action: "include" },
    { scope: "product", id: "ch_mobile_de", action: "include" },
    { scope: "product", id: "ch_mobile_fr", action: "include" },
    { scope: "product", id: "ch_inapp_de", action: "include" },
    { scope: "product", id: "ch_inapp_fr", action: "include" },
    { scope: "proposal", id: "swiss_balanced_v1", action: "include", ask: "focus more on German speakers - try 60/40 instead of 40/60" }
  ]
})

// Seller returns an updated proposal with revised allocations

See get_products refinement for the full workflow and examples.

Executing a Proposal

To execute a proposal, provide the proposal_id and total_budget in create_media_buy:

{
  "buyer_ref": "swiss_q1_campaign",
  "proposal_id": "swiss_balanced_v1",
  "total_budget": {
    "amount": 50000,
    "currency": "USD"
  },
  "brand": { "domain": "acmecorp.com" },
  "start_time": "2025-04-01T00:00:00Z",
  "end_time": "2025-04-30T23:59:59Z"
}

The publisher converts the proposal’s allocation percentages into packages:

ch_desktop_de: 20% × $50,000 =$ 10,000
ch_desktop_fr: 30% × $50,000 =$ 15,000
etc.

This approach simplifies complex multi-line-item campaigns to a single proposal execution.

When Publishers Return Proposals

Publishers include proposals when:

The brief requests specific allocation strategies (channel splits, language splits, etc.)
The publisher can provide strategic guidance based on campaign goals
Multiple products work better together than individually

Publishers typically omit proposals in wholesale mode (the buyer is directing targeting and allocation themselves) or when the brief doesn’t suggest a multi-product strategy. Proposals are optional — publishers may return only products if allocation guidance isn’t applicable. In refine mode, sellers MAY return proposals alongside refined products even when the buyer did not include proposal entries. Proposals are a seller suggestion — allocation and campaign optimization are primarily orchestrator (buyer-side agent) responsibilities.

Delivery Forecasts

Publishers can attach delivery forecasts to proposals and individual allocations to help buyers evaluate expected performance before committing budget. Each forecast contains a points array of one or more ForecastPoints, each pairing a budget level with metric ranges (low/mid/high). A single point is a standard forecast; multiple points ordered by ascending budget show how metrics scale with spend. Metric keys come from two vocabularies:

Delivery/engagement: forecastable-metric enum values (impressions, reach, clicks, spend, views, completed_views, grps, etc.)
Outcomes: event-type enum values (purchase, lead, app_install, add_to_cart, subscribe, etc.)

This lets sellers forecast both delivery (“1.2M impressions”) and outcomes (“1,800 purchases”) in a single forecast. Each forecast declares its method:

estimate — rough approximation based on historical averages or heuristics
modeled — derived from predictive models or historical data
guaranteed — contractually committed delivery levels backed by reserved inventory

Forecast Range Units

The forecast_range_unit field tells consumers how to interpret the points array — what axis the curve represents:

spend (default) — points at ascending budget levels. Standard budget curve.
reach_freq — points at ascending reach/frequency targets. Used in broadcast planning where the publisher shows how cost scales with frequency goals.
weekly / daily — metrics are per-period values. Budget refers to total campaign spend. A frequency of 3.2 with weekly means 3.2 exposures per week.
clicks / conversions — points at ascending outcome targets. Used in goal-based planning (e.g., “tell me your conversion goal, I’ll tell you the budget”).

A spend curve and a reach/frequency curve may contain identical data — the difference is the publisher’s intent. A spend curve says “here’s what different budgets buy.” A reach/frequency curve says “here’s what it costs to hit different frequency targets.” Consumers can read either curve in either direction. Temporal units (weekly, daily) change how metrics are interpreted. Without a range unit (or with spend), a frequency of 3.2 means 3.2 total campaign exposures. With weekly, it means 3.2 exposures per week. Forecasts can appear at two levels:

Proposal-level: aggregate forecast for the entire media plan
Allocation-level: per-product forecast for individual line items

Allocation-level forecasts may not sum to the proposal-level forecast due to audience overlap and frequency capping. When both are present, the proposal-level forecast is authoritative for total delivery estimation. For cross-channel planning, forecasts declare a reach_unit (individuals, households, devices, accounts, cookies) so buyers can compare reach across publishers. GRP-based forecasts (linear TV, radio) use demographic_system and demographic to specify the target demo, following the same pattern as CPP pricing.

Budget Curve

Multiple forecast points at ascending budget levels show how metrics scale with spend, helping buyers find the optimal investment level:

{
  "points": [
    {
      "budget": 25000,
      "metrics": {
        "impressions": { "low": 400000, "mid": 500000, "high": 600000 },
        "reach": { "mid": 180000 },
        "clicks": { "mid": 2000 }
      }
    },
    {
      "budget": 50000,
      "metrics": {
        "impressions": { "low": 850000, "mid": 1050000, "high": 1200000 },
        "reach": { "mid": 320000 },
        "clicks": { "mid": 4200 }
      }
    },
    {
      "budget": 100000,
      "metrics": {
        "impressions": { "low": 1500000, "mid": 1900000, "high": 2200000 },
        "reach": { "mid": 500000 },
        "clicks": { "mid": 7600 }
      }
    }
  ],
  "method": "modeled",
  "currency": "USD",
  "reach_unit": "individuals"
}

The curve reveals diminishing returns — doubling budget from

50K to

100K increases reach by ~56%, not 2x. Buyers can use this to negotiate or reallocate budget across publishers.

CTV with GRP Demographics

TV and audio forecasts use demographic_system and demographic to specify the target demo. This ensures buyer and seller agree on the measurement notation:

{
  "points": [
    {
      "budget": 75000,
      "metrics": {
        "grps": { "low": 45, "mid": 60, "high": 72 },
        "impressions": { "mid": 3200000 },
        "reach": { "low": 800000, "mid": 1100000, "high": 1300000 },
        "frequency": { "mid": 2.9 }
      }
    }
  ],
  "method": "modeled",
  "currency": "USD",
  "demographic_system": "nielsen",
  "demographic": "P18-49",
  "reach_unit": "households"
}

The reach_unit: "households" tells buyers this CTV publisher counts reach by household, not individual. A display publisher reporting reach_unit: "devices" is measuring something different — buyers should not directly compare the two reach numbers.

Retail Media with Outcome Forecasts

Retail media publishers can forecast both delivery metrics and conversion outcomes. Outcome metric keys use event-type values:

{
  "points": [
    {
      "budget": 30000,
      "metrics": {
        "impressions": { "low": 600000, "mid": 750000, "high": 900000 },
        "clicks": { "mid": 6000 },
        "purchase": { "low": 1200, "mid": 1800, "high": 2400 },
        "add_to_cart": { "mid": 4500 }
      }
    }
  ],
  "method": "modeled",
  "currency": "USD"
}

Here impressions and clicks are forecastable-metric values while purchase and add_to_cart are event-type values. Both use ForecastRange (low/mid/high) and coexist in the same metrics map.

Allocation-Level Forecasts

When a proposal includes per-allocation forecasts, buyers can evaluate each product independently:

{
  "proposal_id": "retail_holiday_v1",
  "name": "Holiday Retail Campaign",
  "allocations": [
    {
      "product_id": "sponsored_search",
      "allocation_percentage": 40,
      "forecast": {
        "points": [
          {
            "budget": 20000,
            "metrics": {
              "impressions": { "mid": 500000 },
              "clicks": { "mid": 15000 },
              "purchase": { "mid": 900 }
            }
          }
        ],
        "method": "modeled",
        "currency": "USD"
      }
    },
    {
      "product_id": "offsite_display",
      "allocation_percentage": 60,
      "forecast": {
        "points": [
          {
            "budget": 30000,
            "metrics": {
              "impressions": { "low": 1800000, "mid": 2200000, "high": 2600000 },
              "reach": { "mid": 450000 },
              "purchase": { "low": 400, "mid": 600, "high": 800 }
            }
          }
        ],
        "method": "modeled",
        "currency": "USD",
        "reach_unit": "accounts"
      }
    }
  ],
  "forecast": {
    "points": [
      {
        "budget": 50000,
        "metrics": {
          "impressions": { "low": 2100000, "mid": 2700000, "high": 3100000 },
          "reach": { "mid": 520000 },
          "purchase": { "low": 1100, "mid": 1500, "high": 1900 }
        }
      }
    ],
    "method": "modeled",
    "currency": "USD",
    "reach_unit": "accounts"
  }
}

Note that the allocation forecasts (900 + 600 = 1,500 purchases) happen to match the proposal forecast in this example, but they often won’t — audience overlap and frequency capping mean the whole is typically less than the sum of its parts. The proposal-level forecast is authoritative for total delivery.

Broadcast Audio Spot Plan

Broadcast and audio publishers can return spot-plan proposals with daypart_targets on each allocation and weekly frequency projections via forecast_range_unit: "weekly". This pattern lets the publisher solve the optimization problem — the buyer specifies frequency goals, and the publisher returns the plan that achieves them:

{
  "proposal_id": "iheart_q4_audio",
  "name": "Q4 Audio - Adults 25-54",
  "allocations": [
    {
      "product_id": "morning_drive_30s",
      "allocation_percentage": 50,
      "daypart_targets": [
        {
          "days": ["monday", "tuesday", "wednesday", "thursday", "friday"],
          "start_hour": 6,
          "end_hour": 10,
          "label": "Morning Drive"
        }
      ],
      "rationale": "Morning drive delivers highest reach against P25-54 with 3x weekly frequency at 2 spots/day",
      "forecast": {
        "points": [
          {
            "budget": 37500,
            "metrics": {
              "grps": { "mid": 42 },
              "reach": { "low": 140000, "mid": 180000, "high": 210000 },
              "frequency": { "mid": 3.2 },
              "impressions": { "mid": 576000 }
            }
          }
        ],
        "forecast_range_unit": "weekly",
        "method": "modeled",
        "currency": "USD",
        "demographic_system": "nielsen",
        "demographic": "P25-54",
        "reach_unit": "individuals"
      }
    },
    {
      "product_id": "afternoon_drive_30s",
      "allocation_percentage": 30,
      "daypart_targets": [
        {
          "days": ["monday", "tuesday", "wednesday", "thursday", "friday"],
          "start_hour": 15,
          "end_hour": 19,
          "label": "Afternoon Drive"
        }
      ],
      "rationale": "Afternoon drive complements morning with incremental reach and frequency overlap",
      "forecast": {
        "points": [
          {
            "budget": 22500,
            "metrics": {
              "grps": { "mid": 28 },
              "reach": { "low": 95000, "mid": 120000, "high": 145000 },
              "frequency": { "mid": 2.4 },
              "impressions": { "mid": 288000 }
            }
          }
        ],
        "forecast_range_unit": "weekly",
        "method": "modeled",
        "currency": "USD",
        "demographic_system": "nielsen",
        "demographic": "P25-54",
        "reach_unit": "individuals"
      }
    },
    {
      "product_id": "daytime_30s",
      "allocation_percentage": 20,
      "daypart_targets": [
        {
          "days": ["monday", "tuesday", "wednesday", "thursday", "friday"],
          "start_hour": 10,
          "end_hour": 15,
          "label": "Daytime"
        }
      ],
      "rationale": "Daytime fill provides frequency reinforcement at lower CPP",
      "forecast": {
        "points": [
          {
            "budget": 15000,
            "metrics": {
              "grps": { "mid": 18 },
              "reach": { "low": 60000, "mid": 80000, "high": 95000 },
              "frequency": { "mid": 1.8 },
              "impressions": { "mid": 144000 }
            }
          }
        ],
        "forecast_range_unit": "weekly",
        "method": "modeled",
        "currency": "USD",
        "demographic_system": "nielsen",
        "demographic": "P25-54",
        "reach_unit": "individuals"
      }
    }
  ],
  "forecast": {
    "points": [
      {
        "budget": 75000,
        "metrics": {
          "grps": { "mid": 82 },
          "reach": { "low": 220000, "mid": 280000, "high": 330000 },
          "frequency": { "mid": 4.1 },
          "impressions": { "mid": 1008000 }
        }
      }
    ],
    "forecast_range_unit": "weekly",
    "method": "modeled",
    "currency": "USD",
    "demographic_system": "nielsen",
    "demographic": "P25-54",
    "reach_unit": "individuals"
  }
}

The forecast_range_unit: "weekly" on each forecast tells the buyer that all metrics are per-week values — frequency of 3.2 means 3.2 exposures per week, not 3.2 over the entire campaign. Budget ($75K) is total campaign spend. The daypart_targets on each allocation specify the publisher’s recommended time windows. These are the same structure used in targeting for hard daypart constraints — here the publisher is prescribing the spot plan rather than the buyer constraining it. Note that allocation-level reach doesn’t sum to the proposal level (180K + 120K + 80K > 280K) because of audience overlap across dayparts — the same listener may hear morning drive and afternoon drive spots. The proposal-level forecast accounts for this overlap.

Integration with Discovery

Products are discovered through the Product Discovery process, which uses natural language to match campaign briefs with available inventory. Once products are identified, they can be purchased via create_media_buy.

​The Product Model

​Metric optimization

​Conversion tracking

​Pricing Models

​Supported Pricing Models

​PricingOption Structure

​Delivery Measurement

​Outcome Measurement Object

​CreativePolicy Object

​Placements

​Placement Object Structure

​Example: Product with Placements

​Shows and episodes

​Exclusivity

​When to use each level

​Content sponsorship pattern

​Property Targeting

​Behavior

​Use Cases

​Examples

​Custom & Principal-Specific Products

​Product Examples

​Standard CTV Product (Multiple Pricing Options)

​Auction-Based Display Product

​Retail Media Product with Measurement

​Product Cards

​Card Types

​Structure

​Rendering Cards

​Standard Card Formats

​When to Include Product Cards

​Client Rendering Guidelines

​Proposals

​What Are Proposals?

​Proposal Structure

​Iterating on Proposals

​Executing a Proposal

​When Publishers Return Proposals

​Delivery Forecasts

​Forecast Range Units

​Budget Curve

​CTV with GRP Demographics

​Retail Media with Outcome Forecasts

​Allocation-Level Forecasts

​Broadcast Audio Spot Plan

​Integration with Discovery

​See Also

The Product Model

Metric optimization

Conversion tracking

Pricing Models

Supported Pricing Models

PricingOption Structure

Delivery Measurement

Outcome Measurement Object

CreativePolicy Object

Placements

Placement Object Structure

Example: Product with Placements

Shows and episodes

Exclusivity

When to use each level

Content sponsorship pattern

Property Targeting

Behavior

Use Cases

Examples

Custom & Principal-Specific Products

Product Examples

Standard CTV Product (Multiple Pricing Options)

Auction-Based Display Product

Retail Media Product with Measurement

Product Cards

Card Types

Structure

Rendering Cards

Standard Card Formats

When to Include Product Cards

Client Rendering Guidelines

Proposals

What Are Proposals?

Proposal Structure

Iterating on Proposals

Executing a Proposal

When Publishers Return Proposals

Delivery Forecasts

Forecast Range Units

Budget Curve

CTV with GRP Demographics

Retail Media with Outcome Forecasts

Allocation-Level Forecasts

Broadcast Audio Spot Plan

Integration with Discovery

See Also