feat: add price_breakdown schema for pricing transparency#1594
Merged
Conversation
6 tasks
Adds an optional price_breakdown object to all pricing options and packages, enabling sellers to disclose how fixed_price was derived from the rate card (list_price) through adjustments. Three adjustment kinds: discount (changes buyer price), commission (revenue split only), and settlement (post-invoice terms like cash discounts). Motivated by DBCFM mapping gaps and Swiss market requests, but designed to be market-neutral. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Lets buyer agents discover which adjustment kinds (discount, commission, settlement) apply to a pricing option before negotiation. Driven by DBCFM gap analysis — DBCFM marks each rate with discountable/commissionable/cash_discountable flags. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Schema: change rate maximum to exclusiveMaximum (100% discount is nonsensical). Docs: clarify planning-layer scope (no OpenRTB propagation), list_price is fully-loaded gross, mixed rate/amount invariant example, separate fixed-price vs auction package examples, commission compounding for multi-intermediary, rate/amount constraints, forward compatibility note. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Docs: add explicit formulas for rate/amount application, currency- precision rounding rule, zero-discount edge case (fixed_price must equal list_price), auction list_price convention, rate range notation (0 < rate < 1), seller-populated read-only note on packages, separate eligible_adjustments example ID. Schema: clarify invariant applies only when fixed_price is present, add rounding rule to description. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Adds a fourth adjustment kind (fee) for additive costs like ad serving fees, data/targeting surcharges, and brand safety verification. Without this, these costs are opaque within list_price. The invariant is now: list_price with fee and discount adjustments applied = fixed_price. Adds optional beneficiary field on adjustments to identify who receives the value (sellers.json domain, AdCP account ID, or party name). Enables multi-intermediary transparency for commission reconciliation. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
bokelley
force-pushed
the
bokelley/price-breakdown-schema
branch
from
85a67e9 to
4f30010
Compare
Contributor
Schema Link Check ResultsCommit:
|
This was referenced Apr 28, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds an optional
price_breakdownobject to all pricing options and packages, enabling sellers to disclose howfixed_pricewas derived from the rate card (list_price) through adjustments.Motivation
Driven by DBCFM (German standard) mapping gaps and Swiss market requests. Sellers who need to express multi-step price calculations (rate card → fees → discounts → commissions → settlement terms) currently must use
extobjects, making them unreadable by other AdCP-compliant systems.Design
Four adjustment kinds based on their economic effect:
feediscountcommissionsettlementKey invariant:
list_pricewith allfeeanddiscountadjustments applied sequentially =fixed_price. Fees increase the running price; discounts reduce it. All monetary values rounded to currency precision at each step.Budgets are always denominated at the
fixed_pricelevel, inclusive of commissions. A buyer agent comparing rates across sellers usesfixed_pricedirectly.Optional
beneficiaryfield on adjustments identifies who receives the value (sellers.json domain, AdCP account ID, or party name) for multi-intermediary transparency.Changes
New schemas:
enums/adjustment-kind.json— four-value enum: fee, discount, commission, settlementpricing-options/price-breakdown.json— breakdown object withlist_price, orderedadjustmentsarray, and optionalbeneficiaryper adjustmentModified schemas (added optional
price_breakdownandeligible_adjustments):core/package.json(confirmed line item)Documentation:
Backward Compatibility
Fully backward-compatible. All new fields are optional. Sellers who don't need breakdowns omit
price_breakdownentirely — zero overhead to existing implementations.Test plan
🤖 Generated with Claude Code