RFC #3305 amendment: order-logic scoping — targeting_capabilities on Product + structured targeting on Package (match types, negatives, bid modifiers, audience signals)

[bokelley]

Type: spec amendment to #3305
Target: 3.1 (before GA — establishes the home for order logic before adopters default to platform_extensions)
Severity: load-bearing for adopter onboarding — without it, the first retail-media / search-ads adopter will route bidding rules through platform_extensions and that becomes the de-facto standard
Companion to: forthcoming RFC on product topology — separate axis, both should land together but they're independent design calls

Problem

v2's 11 canonical formats describe the creative envelope — what assets the buyer ships, how the surface renders, what tracking model applies. They say nothing about order logic: match types, negative keywords, bid modifiers, audience signals, day-parting, geo-targeting, device modifiers, frequency caps, budget pacing.

That scoping is correct (the canonical = creative envelope; bidding rules are a separate domain). But it leaves a real gap. Adopters wiring Amazon Sponsored Products, Google Search, Bing Search, Meta lookalike audiences, LinkedIn targeting, TikTok interest categories have no canonical place to:

1. Declare what the product supports at discovery time (e.g., "this product accepts exact/phrase/broad match keywords, negative keyword lists up to 1000 entries, device bid modifiers")
2. Configure the actual values at media-buy time (e.g., "show on exact match for 'wireless earbuds' at $2.50 bid, with negative keyword 'cheap'")

Without a defined home, adopters will stuff this into platform_extensions and per-seller fragmentation returns — exactly the v1 problem v2 was meant to fix.

Proposed change

Two field additions on different surfaces:

(1) Product.targeting_capabilities (new field, schema in core/product.json):

{
  "product_id": "amazon_sponsored_products_us",
  "format_options": [/* canonical narrowings */],
  "targeting_capabilities": {
    "keyword_targeting": {
      "supported_match_types": ["exact", "phrase", "broad"],
      "supports_negative_keywords": true,
      "max_keywords_per_package": 1000,
      "max_negative_keywords_per_package": 1000
    },
    "audience_targeting": {
      "supported_audience_kinds": ["customer_match", "similar_audiences"],
      "supports_negative_audience_lists": false
    },
    "bid_modifiers": {
      "supported_axes": ["device", "placement", "time_of_day"]
    },
    "geo_targeting": {
      "supports_country": true,
      "supports_dma": true,
      "supports_postal_code": false
    },
    "pacing": {
      "supported_pacing_models": ["even", "accelerated"]
    }
  }
}

Per-axis sub-objects (not one umbrella) so each axis has its own vocabulary without an arbitrary umbrella to argue about. Sellers populate only the axes their product supports.

(2) Package.targeting (new field, schema in core/package.json):

{
  "package_id": "pkg_001",
  "product_id": "amazon_sponsored_products_us",
  "targeting": {
    "keyword_targeting": {
      "keywords": [
        { "term": "wireless earbuds", "match_type": "exact", "bid": 2.50 },
        { "term": "bluetooth headphones", "match_type": "phrase", "bid": 1.80 }
      ],
      "negative_keywords": ["cheap", "free"]
    },
    "bid_modifiers": [
      { "axis": "device", "value": "mobile", "modifier": 1.2 }
    ]
  }
}

Validates against the product's targeting_capabilities — buyers can only configure what the product supports. Same axis-key vocabulary on both sides.

Open questions

1. Vocabulary breadth — Amazon SP match types (exact/phrase/broad) ≠ PMax audience signal kinds (customer_match/similar_audiences/lookalike_audiences) ≠ Meta lookalike tiers (1%/2%/5-10%). Do we define per-axis enums (strict, per-platform fragmentation risk) or open string vocabularies with soft-warn registries (loose, less codegen value)? Lean: per-axis enums for the well-understood axes (match types are stable across Amazon / Google / Bing), open strings + registry for the less-converged axes (audience kinds, lookalike tiers).

2. Sub-axis design — How granular per axis? keyword_targeting.supports_negative_keywords: bool vs keyword_targeting.negative_keyword_capabilities: {max_count, supports_phrase, ...}? Lean: start coarse (booleans + counts), grow into typed sub-objects only when adopter pull surfaces.

3. Validation semantics — When the buyer ships Package.targeting.keyword_targeting.keywords[0].match_type: \"exact\" and the product's Product.targeting_capabilities.keyword_targeting.supported_match_types doesn't include exact, what happens? Lean: validation error at media-buy creation; same shape as validate_input for creatives.

4. What's NOT in scope — Budget (already on MediaBuy.total_budget), pricing model (already on pricing_options), creative pacing (different concept). This RFC is specifically about the targeting/bidding axes that aren't captured today.

Why this matters

First retail-media or search-ads adopter to integrate against v2 will ask "where do match types go?" Without an answer they'll route through platform_extensions and other adopters will copy. Three months later we have N per-seller targeting extensions and no shared schema. The canonical-as-contract win for creative envelope evaporates on the targeting side. Better to define the field now, even narrowly, than retrofit after fragmentation.

Companion work

Forthcoming sibling RFC addresses the product topology axis: how to describe a meta-product like PMax that fans out across multiple surfaces with per-surface policies. Different shape, different RFC, but the two should land together so adopters mapping Amazon SP and PMax have a coherent story.

Refs

• #3305 — v2 RFC
• #3307 — v2 implementation branch