Skip to content

RFC: declare price adjustments for buyer-selectable product dimensions #7659

Open

Description

@bokelley

Problem

Product.overlay_support currently makes a uniform-price promise: a binding fixed price or floor applies to every later value permitted by that product's selectable targeting contract. If a seller's rate depends on the selected value, it must return a request-specific configured product after rediscovery, split the inventory into separately priced products, or expose only non-binding guidance.

Common rate cards vary price by format, property, collection, placement, activation route, or reporting tier. Modeling each price-bearing value as another product or another discovery round trip makes otherwise selectable dimensions expensive to use.

Signal targeting already avoids part of this problem: signal_targeting_options[].pricing_options prices a selectable signal on the product itself.

IAB Tech Lab's draft OpenProposal 3.0 uses the same general idea for every selectable field: a seller declares the available and included values plus an optional per-option price delta (§3.1 and the selectable fields in §5). It does not define how multiple adjustment types compose; AdCP should.

Proposed direction

Add an optional ordered price_adjustments table to binding fixed-price product pricing options.

  • Each row identifies one eligible selectable dimension and value/ref, then declares a fee or discount using exactly one of rate or amount.
  • The product-level fixed_price remains the base/default rate. All rows matching the buyer's concrete selections are applied in declared array order.
  • The accepted purchase's pricing.fixed_price is the resolved rate. Its price_breakdown records the applied rows in the same order, using the existing invariant: list_price plus sequential fee/discount adjustments equals fixed_price.
  • The full adjustment table remains part of the selected pricing option's binding terms and is therefore covered by commercial_terms.terms_digest. This matters when accepted terms permit a later targeting change.
  • A change to the adjustment table or its applicability mints a new pricing_option_id, like any other change to a binding price, floor, currency, model, or priced applicability.
  • When ProductPurchaseInput.pricing is omitted, the seller computes the resolved pricing. When the buyer supplies it, the seller MUST reject a mismatch with the declared table; it MUST NOT silently reprice the request.
  • Amend the current overlay_support uniform-price language to say that fixed prices remain uniform except for adjustments declared on the selected pricing option.

Auction floors are out of scope for the first version. Forecast and availability remain seller-computed: the price can resolve locally, but feasibility cannot.

Decisions needed

  1. Which dimensions are eligible in the first version? Candidate keys are format option, property/collection/placement selection, activation method, measurement vendor, and reporting tier.
  2. When a dimension permits multiple values, is its adjustment applied once per matching value or once for the dimension?
  3. Can multiple rows match the same selection, and if so, is declared array order sufficient to make the result deterministic?
  4. Are percentage-on-percentage adjustments allowed, or should all fixed amounts be applied before rates?
  5. Do accepted terms permit any post-acceptance selection changes that require retaining the unapplied table, or should every such change require an amendment?

Acceptance criteria

  • Add a strict schema for the declared table and typed selection keys.
  • Define deterministic matching, ordering, currency rounding, and resolved-price rules.
  • Carry the resolved fixed_price and applied price_breakdown into accepted commercial terms.
  • Update product, pricing, overlay-support, and proposal lifecycle documentation.
  • Add compliance vectors for one adjustment, multiple ordered adjustments, an unmatched selection, buyer-supplied pricing mismatch, and changed-table/new-ID enforcement.

Activity

  1. added this to the 3.3.0 milestone on Sep 23, 2026
  2. added
    rfcProtocol change — auto-adds to roadmap board
    schemaJSON Schema source-of-truth: definitions, codegen artifacts, validation, hygiene
    needs-wg-reviewBlocked on a working-group decision — surface in WG meeting agendas
    media-buyIssue concerns the media-buy protocol domain
    on Sep 23, 2026
  3. added
    claude-triagingTriage routine is actively working on this issue (1-3 min)
    on Sep 23, 2026
  4. bokelley commented on Sep 23, 2026

    @bokelley
    ContributorAuthor

    Triage

    Classification: RFC — Normative feature proposal
    Bucket(s): spec / protocol, media-buy, schema
    Status: ready-for-human
    Milestone: 3.3.0

    What the experts said:

    • ad-tech-protocol-expert: Non-breaking MINOR addition (new optional field on canonical-pricing-option.json); D1 blocks schema authoring — format_option, activation_method, measurement_vendor, reporting_tier have no anchors in targeting-overlay-support.json; D2/D3/D4 need explicit normative composition text; D5 is settled by DR-0016.
    • adtech-product-expert: Problem is real — format surcharges, PG/PMP activation premiums, and measurement vendor add-ons are standard line items on premium direct deals; modifier table risks buyer-seller price disagreement at invoice without a canonical composition rule; proposes per-selection pricing option as an alternative that eliminates modifier math.

    My take: The arithmetic primitives already exist (price-breakdown.json's sequential running-total invariant), and four of the five open questions have clear protocol answers. Two require WG decision before the schema can be written: which representation primitive to adopt, and which dimensions to scope in v1.


    Decisions with clear protocol answers

    D2 — Multi-value dimension: Once-per-dimension, not once-per-value. A $2 CPM format surcharge fires once even if the buyer selects five properties. Spec MUST state: each matching row fires at most once per eligible dimension per purchase.

    D3 + D4 — Composition rule: Sequential running total, matching the existing price-breakdown.json invariant. Fixed amounts and percentage rates interleave in declared array order; each rate row applies to the running total after all prior rows (10% + 10% = 21%, not 20%). This must be normative, not advisory.

    D5 — Post-acceptance selection changes: DR-0016 answers this. Unapplied rows are part of the frozen commercial snapshot covered by terms_digest. A dimension change that alters the resolved price requires a new accepted proposal unless an explicit change_terms[] entry permits it. No new mechanism needed; cite DR-0016.


    WG decisions needed

    Q1 — Representation primitive (blocks schema authoring):

    Option A — Modifier table on pricing option (proposed):

    {
      "pricing_option_id": "opt-v3",
      "pricing_model": "cpm",
      "currency": "USD",
      "fixed_price": 20.00,
      "price_adjustments": [
        { "dimension": "format_option", "value_ref": "video_30s", "kind": "fee", "amount": 2.00 },
        { "dimension": "activation_method", "value_ref": "pg", "kind": "fee", "rate": 0.15 }
      ]
    }
    // Buyer selects video_30s + pg → $20 + $2 = $22; +15% of $22 = $25.30
    // Requires: normative composition rule + once-per-dimension MUST language

    Compact for orthogonal dimensions; buyer must implement modifier math; price agreement depends on both sides applying the same composition rule.

    Option B — Per-selection pricing options (alternative; no new schema fields):

    // Seller declares a fully-resolved pricing option per selection combination
    {
      "pricing_option_id": "opt-video30s-pg",
      "pricing_model": "cpm",
      "currency": "USD",
      "fixed_price": 25.30,
      "price_breakdown": {
        "list_price": 20.00,
        "adjustments": [
          { "kind": "fee", "name": "30s_format", "amount": 2.00 },
          { "kind": "fee", "name": "pg_activation", "rate": 0.15 }
        ]
      }
    }
    // Buyer reads fixed_price directly — no modifier math, no composition ambiguity
    // Tradeoff: combinatorial pricing option catalog for orthogonal selectable dimensions

    Q2 — V1 eligible dimensions (depends on Q1 answer):

    Option A — overlay_support-anchored only: property_list, collection_list, placement_selection — all currently declared in targeting-overlay-support.json. No new schema anchors needed. Format, activation, and measurement vendor deferred to v2.

    Option B — Commercial-need first: format_option, activation_method, measurement_vendor — highest-priority per operator reality (format surcharges, PG/PMP premiums, IAS/DV/Nielsen add-ons), but these fields are not currently enumerable dimension anchors in overlay_support. Would require either a new dimension enum in the schema or extending overlay_support before schema authoring is complete.


    No existing decision record governs either question. No open PRs cover this surface. Once Q1 is resolved, the schema spec (acceptance criterion 1), composition rules (criterion 2), and compliance vectors (criterion 5) can be authored as a single Normative PR; criteria 3 and 4 follow.


    Triaged by Claude Code. Session: https://claude.ai/code/session_018QYubFyMdY6APCHsHeAjNW


    Generated by Claude Code

  5. added
    claude-triagedIssue has been triaged by the Claude Code triage routine. Remove to re-triage.
    and removed
    claude-triagingTriage routine is actively working on this issue (1-3 min)
    on Sep 23, 2026
  6. bokelley commented on Oct 6, 2026

    @bokelley
    ContributorAuthor

    Updated 2026-10-08: Pulled back to the live WG agenda. Dutch TV rate cards compound indices (see comment above), so #7955 now proposes two kinds, additive premiums and multiplicative indices, plus validity windows. Open question: do premiums apply to the base or to the indexed price?

    WG decision brief (3.3)

    Problem. Product.overlay_support makes a uniform-price promise: a binding price applies to every later selectable value and date, so a seller whose rate depends on format, placement, or the month must split inventory into extra products or force a rediscovery round trip. Dutch linear TV sales houses price GRPs as a net base multiplied by month, spot-length, target-audience and market indices, with position surcharges on top (#8009). Pulling: the RFC author, the Dutch TV pilot, IAB Tech Lab OpenProposal 3.0 (selectable fields with price deltas; its delta_pct has no composition rule and its comment period closes 2026-10-22, an alignment opportunity), #8001 (:30 equivalization), #8009, #8010, and #7662 (blocked on this table).

    Proposed shape. Draft PR: #7955 (additive, optional; docs, vectors with a reference resolver).

    { "pricing_model": "cpp", "currency": "EUR", "fixed_price": 1000.00, "price_adjustments": [
      { "dimension": "always", "kind": "index", "name": "month_index_nov", "factor": 1.10,
        "valid_from": "2026-11-01T00:00:00+01:00", "valid_until": "2026-12-01T00:00:00+01:00" },
      { "dimension": "always", "kind": "index", "name": "market_index_nov", "factor": 0.95, "valid_from": "...", "valid_until": "..." },
      { "dimension": "format_option", "format_option_ref": { "scope": "product", "format_option_id": "spot_20s" },
        "kind": "index", "name": "spot_length_20s", "factor": 0.80 },
      { "dimension": "always", "kind": "index", "name": "target_audience_a25_54", "factor": 1.25 },
      { "dimension": "placement_selection", "placement_ref": { "publisher_domain": "oranjetv.example", "placement_id": "first_in_break" },
        "kind": "fee", "name": "first_in_break_premium", "rate": 0.20 } ] }
    // indexed = 1000 x 1.10 x 0.95 x 0.80 x 1.25 = 1045.00; premium 20% of 1045.00 = 209.00; resolved 1254.00
    // price_breakdown: four index rows (fee/discount rates) + premium row (209.00 amount), table retained in terms_digest
    • Index rows (factor) compound in declared order; premium rows (fee/discount, rate or amount) add. Fixed amounts are not indexed; premiums never compound with each other. Selection rows fire once per dimension (first applicable row); always rows each fire. Spot length is an index keyed to a format option, which also carries :30 equivalization rates (Broadcast TV: demo-bound CPM guarantees and :30 equivalization #8001's reporting side is not solved here).
    • Windows: valid_from (inclusive) / valid_until (exclusive), evaluated at the purchase start_time; a flight crossing a boundary is rejected and the buyer splits it per window.
    • Rounding: each delta rounds half away from zero to price precision (currency exponent, 4 dp for per-unit models, or the decimals needed to represent declared values exactly, by numeric value); the price is the exact sum and never negative. A buyer-supplied pricing that disagrees gets INVALID_REQUEST with the resolved price and breakdown; a changed table gets a new pricing_option_id; post-acceptance changes follow DR-0016.
    • Marked experimental (media_buy.price_adjustments: one named pilot, field set still growing); the sub-3.3 caller gate stays an additional MUST. Index factor has no upper bound (prime-position indices exceed 2); premium rate stays below 1 with amount as the escape hatch. Rate-side spot-length indexing is expressible here; impression-side :30 equivalization and demo-bound CPM remain Broadcast TV: demo-bound CPM guarantees and :30 equivalization #8001 / 3.4. Position in break is a seller-published placement until Linear TV: book and report position in break (first/last in break) #8009's booking half lands.
    • Settled, no vote needed: modifier table (per-selection options stay valid and are the fallback for callers pinned below 3.3); v1 selectors are format_option, placement_selection, always (buyer-owned property/collection lists cannot be priced by a seller; position in break Linear TV: book and report position in break (first/last in break) #8009, activation, measurement vendor and reporting tier have no anchor yet); once per dimension; auction floors out of scope.

    Open questions for the WG

    1. Premium basis: do percentage premiums apply to the base or to the indexed price? Rec: the indexed price (the PR's default). Position and cover surcharges are quoted on top of the rate the sales house shows after indexing, and the Dutch pilot lists them after the index stack. Evidence is thin: no public source I found states the order, and print quotes premiums against the "earned rate", which is already net of program discounts. The two bases differ only when an index and a premium rate both fire (above: 1254.00 vs 1245.00). A per-row basis can be added later without breaking this default.
    2. Cross-window flights: reject and split per window, or resolve per installment/day? Rec: reject and split (per-purchase resolution at start_time). A purchase carries one resolved fixed_price; per-installment or per-day resolution needs a price per installment in the accepted snapshot, which is not a bounded 3.3 change. Revisit with installments in 3.4.
    3. Should the negotiated discount also reduce fixed-amount surcharges? yes/no. Today fixed_price is net of the option's declared discounts and row amount values are not reduced (percentage rows are unaffected, since they use the net indexed price). Rec: no: amounts are the seller's quoted surcharges, and sellers who want discounted surcharges publish them net.
    4. Should a dimension support SUM of matched values (GAM SUM vs HIGHEST)? yes/no. One row fires per dimension, so ordering reproduces HIGHEST but not SUM. Rec: no for 3.3, add later: a per-dimension match mode defaulting to first-match is additive, and multi-select cases can use separate packages or per-selection options meanwhile.

    Out of scope / deferred

  7. bokelley commented on Oct 8, 2026

    @bokelley
    ContributorAuthor

    Linear TV rate cards as a test case. Dutch TV sales houses price GRPs as a net base price multiplied by a stack of indices: month, spot length, target audience and a monthly market index. Preferred position in break (#8009) and late booking after a request round closes (#8010) add further surcharges. Trade press puts the effect of the index stack at 30% or more.

    Two asks for the design:

    1. Allow multiplicative adjustments, not only additive ones, and say how several adjustments combine (multiply in a declared order versus add percentages). Otherwise an agent's quote and the invoice will disagree.
    2. Allow time-bound adjustments. Month and market indices change every month, so an adjustment needs a validity window (or must belong to a dated product or collection).

    Spot-length indexing is also the "equivalization" problem in #8001, so it might be worth one mechanism for both.

  8. bokelley commented on Oct 19, 2026

    @bokelley
    ContributorAuthor

    WG decision (Session B, 2026-10-19): not decided; the use case needs validating first. Open question: are these coefficients used across the board (e.g. imposed by a JIC or industry body), or are they one publisher's pricing strategy? If a JIC imposes them, AdCP should support them, possibly by pointing at an agreed external rate-card file rather than encoding the formula. If they're publisher-specific, they may belong to the vendor or order-management layer. The source was Ster (the Dutch public broadcaster). Action: Ben is surveying TV and radio broadcasters (including Telpa) and will report back to the broadcast working group. Konstantin will look at a more generic, vendor-extensible pricing mechanism. #7955 stays draft pending both and won't be in beta.0.

  9. 24 remaining items

  10. bokelley commented on Nov 11, 2026

    @bokelley
    ContributorAuthor

    Moved to the 4.0 milestone. price_adjustments stays out of 3.3.0 (see the Nov 7 correction above). Per RFC #8756 it's a rider for the 4.0 betas, together with #8654.

    🤖 Generated with Claude Code

  11. added 14 commits that reference this issue on Nov 12, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    claude-triagedIssue has been triaged by the Claude Code triage routine. Remove to re-triage.media-buyIssue concerns the media-buy protocol domainrfcProtocol change — auto-adds to roadmap boardschemaJSON Schema source-of-truth: definitions, codegen artifacts, validation, hygienespec / protocol

    Type

    No type

    Projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions