feat(schema): redesign optimization_goal as optimization_goals array

.changeset/optimization-goals-array.md

@@ -0,0 +1,14 @@
+---
+"adcontextprotocol": minor
+---
+
+Redesign optimization goals with multiple event sources, threshold rates, and attention metrics.
+
+- `optimization_goal` (singular) → `optimization_goals` (array) on packages
+- `OptimizationGoal` is a discriminated union on `kind`:
+  - `kind: "event"` — optimize for advertiser-tracked conversion events via `event_sources` array of source-type pairs. Seller deduplicates by `event_id` across sources. Each entry can specify `value_field` and `value_factor` for value-based targets.
+  - `kind: "metric"` — optimize for a seller-native delivery metric with optional `cost_per` or `threshold_rate` target
+- Target kinds: `cost_per` (cost per unit), `threshold_rate` (minimum per-impression value), `per_ad_spend` (return ratio on event values)
+- Metric enum: `clicks`, `views`, `completed_views`, `viewed_seconds`, `attention_seconds`, `attention_score`
+- Both kinds support optional `priority` (integer, 1 = highest) for multi-goal packages
+- `product.conversion_tracking.supported_optimization_strategies`: `target_cost_per`, `target_threshold_rate`, `target_per_ad_spend`

docs/guides/commerce-media.mdx

@@ -20,7 +20,7 @@ What makes commerce media unique is **closed-loop attribution**. Retailers know
 | Sponsored product listing | Product with catalog-rendered creative | [Creative Formats](/docs/creative/formats) |
 | On-site display / video | Product with standard `format_ids` | [Media Products](/docs/media-buy/product-discovery/media-products) |
 | Retailer first-party audience | Brief-based; named segments via `data_provider_signals` | [Targeting](/docs/media-buy/advanced-topics/targeting) |
-| ROAS target / max conversions | `optimization_goal` on package | [Optimization & Reporting](/docs/media-buy/media-buys/optimization-reporting) |
+| ROAS target / max conversions | `optimization_goals` on package | [Optimization & Reporting](/docs/media-buy/media-buys/optimization-reporting) |
 | Closed-loop measurement | `measurement` + `conversion_tracking` on product | [Delivery Reporting](/docs/media-buy/task-reference/get_media_buy_delivery) |
 | Attribution window (14d click, 1d view) | `attribution_window` in delivery response | [Delivery Reporting](/docs/media-buy/task-reference/get_media_buy_delivery) |
 | ROAS / attributed revenue | `roas`, `conversion_value` in delivery metrics | [Delivery Reporting](/docs/media-buy/task-reference/get_media_buy_delivery) |
@@ -74,7 +74,7 @@ The simplest commerce media product. The retailer renders the creative from the
   },
   "conversion_tracking": {
     "action_sources": ["website", "app", "in_store"],
-    "supported_optimization_strategies": ["maximize_conversions", "target_roas"],
+    "supported_optimization_strategies": ["target_cost_per", "target_per_ad_spend"],
     "platform_managed": true
   },
   "creative_policy": {
@@ -94,7 +94,7 @@ The `catalog_types` field declares what catalog types this product supports. The
 Key characteristics:
 - **CPC pricing** with auction-based bidding
 - **`platform_managed: true`** — the retailer provides always-on purchase attribution
-- **`supported_optimization_strategies`** — tells buyers they can set `target_roas` or `maximize_conversions` on packages via `optimization_goal`
+- **`supported_optimization_strategies`** — tells buyers which optimization strategies are available when setting `optimization_goals` on packages
 - **`templates_available: true`** — the retailer renders creatives from catalog data
 - **`action_sources`** includes `in_store` for omnichannel attribution
 
@@ -388,11 +388,14 @@ A single media buy can span multiple product types and retailers. Each package t
       "budget": 15000,
       "bid_price": 1.10,
       "pacing": "even",
-      "optimization_goal": {
-        "event_source_id": "grocery_retailer_purchases",
-        "event_type": "purchase",
-        "target_roas": 3.0
-      }
+      "optimization_goals": [{
+        "kind": "event",
+        "event_sources": [
+          { "event_source_id": "grocery_retailer_purchases", "event_type": "purchase", "value_field": "value" }
+        ],
+        "target": { "kind": "per_ad_spend", "value": 3.0 },
+        "priority": 1
+      }]
     },
     {
       "buyer_ref": "onsite_display",
@@ -411,7 +414,7 @@ A single media buy can span multiple product types and retailers. Each package t
 }
 ```
 
-The `account` identifies the brand's billing relationship with this retailer. The sponsored products package uses catalog selectors (`gtins`, `tags`) to specify which items to promote and `optimization_goal` to tell the retailer to optimize for purchases at a 3x ROAS target. The display and premium packages use standard creative workflows.
+The `account` identifies the brand's billing relationship with this retailer. The sponsored products package uses catalog selectors (`gtins`, `tags`) to specify which items to promote and `optimization_goals` with a `per_ad_spend` target to tell the retailer to optimize for 3x return on purchase value. The display and premium packages use standard creative workflows.
 
 ### Delivery Reporting
 
@@ -494,7 +497,7 @@ Products signal closed-loop capability through two fields:
 {
   "conversion_tracking": {
     "action_sources": ["website", "app", "in_store"],
-    "supported_optimization_strategies": ["maximize_conversions", "target_roas"],
+    "supported_optimization_strategies": ["target_cost_per", "target_per_ad_spend"],
     "platform_managed": true
   }
 }
@@ -538,7 +541,7 @@ Different retailers use different attribution windows (e.g., 14-day click vs. 7-
 1. **Set up accounts early** — use `list_accounts` to confirm your billing relationship with each retailer before placing buys
 2. **Sync product and inventory feeds early** — product and inventory catalogs should be synced to the account before creating buys. Inventory feeds update hourly; product feeds daily.
 3. **Reference retailer store catalogs in targeting** — the retailer's store locations and catchment areas are platform-side data. Use them for proximity targeting without needing to sync your own store catalog.
-4. **Use `optimization_goal`** — set `target_roas` or `target_cpa` on packages to let the retailer optimize delivery against their purchase data
+4. **Use `optimization_goals`** — set event goals with `cost_per` or `per_ad_spend` targets on packages to let the retailer optimize delivery against their purchase data
 5. **Use catalog selectors strategically** — `gtins` for specific products, `tags` or `category` for broad promotions
 6. **Budget across the funnel** — sponsored products for conversion, on-site display for awareness, off-site for reach extension
 7. **Compare attribution windows** — use `attribution_window` in delivery reports to normalize ROAS across retailers with different lookback windows
@@ -547,7 +550,7 @@ Different retailers use different attribution windows (e.g., 14-day click vs. 7-
 
 1. **Model product types separately** — sponsored products, on-site display, off-site, and premium placements should be distinct products with appropriate pricing and formats
 2. **Declare `catalog_requirements`** on formats that need product or inventory data — buying agents check these before syncing catalogs
-3. **Declare `conversion_tracking`** with `platform_managed: true` and list `supported_optimization_strategies` so buyers know they can set `optimization_goal` on packages
+3. **Declare `conversion_tracking`** with `platform_managed: true` and list `supported_optimization_strategies` so buyers know which goal targets are available on packages
 4. **Include `attribution_window`** in delivery responses — buyers comparing across retailers need to know your lookback windows and model
 5. **Report `by_action_source`** to show omnichannel impact — website, app, and in-store conversions
 6. **Return `catalog_match`** on sponsored product listings so buyers can see which GTINs/SKUs are eligible
@@ -563,6 +566,6 @@ Different retailers use different attribution windows (e.g., 14-day click vs. 7-
 - [Catalogs](/docs/creative/catalogs) — Product, inventory, store, and promotion feeds
 - [Brand identity](/docs/brand-protocol/brand-json) — Product catalog and brand identity
 - [Pricing Models](/docs/media-buy/advanced-topics/pricing-models) — CPC, CPM, flat rate details
-- [Optimization & Reporting](/docs/media-buy/media-buys/optimization-reporting) — `optimization_goal` and conversion optimization
+- [Optimization & Reporting](/docs/media-buy/media-buys/optimization-reporting) — `optimization_goals` and conversion optimization
 - [Delivery Reporting](/docs/media-buy/task-reference/get_media_buy_delivery) — Commerce attribution metrics
 - [Targeting](/docs/media-buy/advanced-topics/targeting) — Brief-based targeting approach

docs/media-buy/advanced-topics/pricing-models.mdx

@@ -255,7 +255,7 @@ Buyers should verify the measurement provider meets their campaign requirements
 }
 ```
 
-**Billing**: Charged a fixed price when the specified `event_type` fires. The pricing option declares what event triggers billing — this is independent of `optimization_goal`, which controls delivery optimization.
+**Billing**: Charged a fixed price when the specified `event_type` fires. The pricing option declares what event triggers billing — this is independent of `optimization_goals`, which controls delivery optimization.
 
 **Parameters**:
 - `event_type` (required): The conversion event that triggers billing. Uses the standard event type enum (e.g., `purchase`, `lead`, `app_install`, `add_to_cart`, `subscribe`).
@@ -285,7 +285,7 @@ Buyers should verify the measurement provider meets their campaign requirements
 }
 ```
 
-**Pricing vs. optimization**: The CPA pricing option's `event_type` (what triggers billing) is independent of the package's `optimization_goal` (what the platform optimizes delivery toward). For example, a package can use CPA pricing on `lead` events while setting `optimization_goal.event_type: "purchase"` with `target_roas: 4.0` — billing fires on leads, but delivery is optimized for downstream purchase ROAS.
+**Pricing vs. optimization**: The CPA pricing option's `event_type` (what triggers billing) is independent of the package's `optimization_goals` (what the platform optimizes delivery toward). For example, a package can use CPA pricing on `lead` events while setting an event goal with `event_sources` containing purchase events and `target: { kind: "per_ad_spend", value: 4.0 }` — billing fires on leads, but delivery is optimized for downstream purchase return.
 
 **Refunds and adjustments**: Refund handling and conversion adjustment policies are commercial terms between buyer and seller. The protocol does not govern clawbacks or billing credits for refunded conversions.