Repository navigation
Description
Problem
AdCP has two reconciliation models that never reference each other.
Billing authority (3.0–3.1, shipped). measurement_terms.billing_measurement on the package names the party whose count of the billing metric governs invoicing: the seller's ad server, the buyer's third-party ad server, or a named measurement vendor. It carries max_variance_percent, measurement_window, and finalization_deadline_hours. When the authoritative party is not the seller, the buyer pushes settled numbers through report_usage, the seller compares within tolerance, and makegood_policy governs remedies. docs/media-buy/advanced-topics/billing-authority.mdx notes a structured dispute task was "targeted for 3.2"; it does not exist.
Reliable Reporting (3.2, experimental). Obligations, immutable revisions with a JCS + SHA-256 binding, get_reporting_status, opt-in sync_reporting_status, and the Reconciled Billing tier with sync_reporting_receipts and post-official adjustments.
Neither surface mentions the other. grep -rn "billing_measurement\|report_usage" over the Core guide, both status tasks, receipts, and every reporting-*.json schema returns nothing. report_usage has no obligations, no immutability, no binding hash, no status surface, and no supersession.
Failure scenario. A package names the buyer's ad server (adserver.buyer.example) as billing basis within 10%. The seller's official revision is 12% above the buyer's count. Every Reliable Reporting signal is green: buyer status received, receipt accepted, health complete. The invoice is disputed over email. The protocol reports a settled period that is not settled.
Why now
sync_reporting_status becomes required Core in the next eligible minor after 2026-10-24. Three current schemas encode "the seller is always the producer" and will need a breaking change if a buyer-authoritative feed is added later:
core/reporting-delivery-config.jsonallOf:feed_purpose: billingforcesreconciliation_mode: consumer_receipt, which forcesmethod. A Core-tier buyer-basis billing feed is schema-illegal.core/reporting-consumer-status.jsonattribution text: consumer submissions "never overwrite or become authoritative … revision … evidence".core/reporting-reliability-statistics.json,production_status, andrevision_countassume seller production.
Proposal
Reserve now (3.2 experimental window, additive)
Add optional authoritative_party: "seller" | "consumer" to reporting-delivery-config.json, default seller. Sellers MUST reject consumer until the 3.3 task exists (UNSUPPORTED_FEATURE). Relax the billing-feed allOf so it applies only when authoritative_party is seller. Add a one-line carve-out to the consumer-status attribution text. No behavior change for any current implementation.
Define in 3.3
sync_reporting_revisions (buyer → seller, same transport as sync_reporting_status; no buyer-hosted endpoint, no webhook). The buyer deposits an immutable consumer revision for one (account, delivery_config_id, delivery_config_version, report_definition_id, period):
consumer_revision_id,supersedes_consumer_revision_id(append-only chain, same semantics as consumer status)finality,row_count,control_totals[], boundedreporting_rows[],revision_content_sha256over the same JCS binding Core already usessourceas a BrandRef matchingbilling_measurement.vendor
Seller behavior: validate against the caller's configuration generation, record idempotently, compare control totals for the billing metric against its own current revision using the package's max_variance_percent, and project one of:
- within tolerance → obligation satisfied on the consumer's numbers; the seller invoices on those numbers per the existing billing-authority flow
- outside tolerance →
action_required/VARIANCE_EXCEEDEDcarrying both values, the threshold, and themakegood_policyremedy menu - consumer revision overdue past
finalization_deadline_hours→action_required/CONSUMER_REVISION_OVERDUE,responsible_party: buyer
Obligations, the five health states, expected_at, and changes_after repair work unchanged; only the party that owes the revision flips.
Seller-authoritative with a third-party check (the more common case): a lightweight reporting-comparison record submitted through the same task with control_totals but no rows, so a buyer can register "my ad server saw N" against a seller revision without becoming billing basis. Same VARIANCE_EXCEEDED projection.
Scope boundary. Measurement that is not a billing basis (viewability, attention, incrementality) stays in vendor_metric_values, committed_metrics, and provide_performance_feedback. This issue covers only what billing_measurement names.
Retire the gap
Document report_usage for media-buy billing as the pre-Reliable-Reporting path and point it at sync_reporting_revisions once shipped. The structured dispute lifecycle promised in billing-authority.mdx should land on reporting-status-issue.json (issue_state, resolved_by, resolution_code) so both loops share it.
SDK implications
Seller SDKs should own the whole ledger behind one adapter (a source callback returning rows, null for not-ready, [] for a real zero) so a one-developer publisher never sees obligations. The buyer SDK gains one optional billingSource adapter used only when a package names a buyer-side basis. Neither side writes comparison code; the SDK already has the package terms. Current state: @adcp/sdk and adcp (Python) both ship buyer-side reconcileReporting / reconcile_reporting_core but expose get_reporting_status only as an unimplemented seller handler slot.
Acceptance
-
authoritative_partyreserved inreporting-delivery-config.jsonwith theallOfrelaxation and consumer-status carve-out, before the Core requirement lands -
sync_reporting_revisionsrequest/response schemas,reporting-consumer-revision.json,VARIANCE_EXCEEDEDandCONSUMER_REVISION_OVERDUEissue codes - Core guide and billing-authority doc cross-reference each other;
report_usagemedia-buy billing path marked as predecessor - Capability-gated storyboard: buyer-basis feed within tolerance, outside tolerance, overdue
- Reference seller SDK module demonstrates a seller passing the storyboard with zero comparison code
Related
- RFC: reliable reporting status and managed delivery #6911 (Reliable Reporting RFC), Proposal: unify operational snapshots and official delivery as revisioned facts #6122 (revisioned delivery facts), Reporting metric aggregation needs executable semantics #7240 (metric aggregation semantics)
- PR feat(reporting): add consumer status sync loop #7436 (
sync_reporting_status) docs/media-buy/advanced-topics/billing-authority.mdx,docs/media-buy/reporting-core-implementation-guide.mdx
🤖 Generated with Claude Code
Metadata
Metadata
Assignees
Labels
Type
Projects
- StatusShow more project fieldsNo status
Activity
bokelley commentedon Sep 13, 2026
Triage
Classification: RFC — protocol change proposal
Bucket(s): spec / protocol, media-buy, rfc
Status: ready-for-human
What the experts said:
allOfmakes buyer-basis Core configs schema-invalid today (feed_purpose: billing→reconciliation_mode: consumer_receipt→methodrequired, but Core omitsmethod). Interop gap is a real protocol failure, not just a product-layer gap. Industry precedent is strong (CM360→DFP, Flashtalking→Xandr 3PAS flows). Unresolved:sync_reporting_revisionsvs. existingreport_usagecoexistence needs a precedence rule before 3.3 can land safely.authoritative_partyon the delivery config can conflict withbilling_measurement.vendoron the package — a buyer could setauthoritative_party: consumeron a config for a deal whose vendor names the seller's ad server. Better placement: onmeasurement_termsat deal time. TheallOfrelaxation as written could silently allow receipt-free seller-authoritative billing, which is a behavioral regression.reporting-consumer-status.jsondoes not yet exist in the repo — PR feat(reporting): add consumer status sync loop #7436 introduces it — so any 3.3 ratification that references this schema is premature. Three decisions need WG votes: (a)authoritative_partyplacement, (b) new task vs. receipt extension, (c) authorization boundary for buyer deposit.report_usageretirement framing is the RFC's biggest error — the task serves five billing domains (signals, governance, creative, brand/rights, media-buy 3PAS); only the last one overlaps. Retirement notice must be scoped narrowly. Alternative to the new task: extendsync_reporting_receiptswithrevision_type: buyer_deposited— health states and variance checks attach to the existing receipt/ledger surface without a parallel state machine. Theauthoritative_partyreservation is a convenience, not a correctness requirement on an experimental surface (could patch aftersync_reporting_statusships).My take: The gap is real —
billing-authority.mdxline 113 explicitly promises a structured dispute task for 3.2 that does not exist, and the schema illegality blocks the buyer-authoritative billing path at the Core tier. Two design forks need a human call before implementation can start:@bokelley, your call on two decisions:
Decision 1 — where does
authoritative_partylive?Option A — on the delivery config (RFC's proposal). Keeps billing basis at the reporting layer; risk of conflict with
billing_measurement.vendoron the package.{ "delivery_config_id": "cfg_billing_q3", "feed_purpose": "billing", "authoritative_party": "consumer", "reconciliation_mode": "consumer_receipt" }Option B — on
measurement_termsat deal time (eliminates dual-encoding conflict; config derives the value from the package). Requires config-level logic to readbilling_measurement.vendorrather than set a new field."billing_measurement": { "vendor": { "domain": "adserver.buyer.example" }, "max_variance_percent": 10, + "authoritative_party": "consumer" }Decision 2 — buyer-deposit mechanism: new task or receipt extension?
Option A — new
sync_reporting_revisionstask (RFC's proposal). Parallel buyer→seller push;CONSUMER_REVISION_OVERDUEis the only recovery path if the buyer goes silent.{ "consumer_revision_id": "rev_q3_v1", "delivery_config_id": "cfg_billing_q3", "period": "2026-Q3", "control_totals": [{ "metric": "impressions", "value": 1423000 }], "revision_content_sha256": "abc123..." }Option B — extend
sync_reporting_receiptswithrevision_type: buyer_deposited. Health states and variance checks stay in the existing receipt/ledger surface; no new task state machine.{ "receipt_id": "rcpt_q3", "delivery_config_id": "cfg_billing_q3", + "revision_type": "buyer_deposited", + "control_totals": [{ "metric": "impressions", "value": 1423000 }] }Pre-ratification blockers (either path):
reporting-consumer-status.jsonis unwritten — PR feat(reporting): add consumer status sync loop #7436 introduces it. The RFC's 3.2 consumer-status carve-out must coordinate with that PR before landing.report_usageretirement notice must be scoped tomedia_buy_idrecords wherebilling_measurement.vendornames the caller as billing basis — not the full task.authoritative_party: consumeris set on a config butbilling_measurement.vendornames the seller's ad server?Triaged by Claude Code. Session: https://claude.ai/code/session_01C34dFCQFiJ4sYjzC7REUHF
Generated by Claude Code
lukasz-pubx commentedon Nov 17, 2026
Worked example: a UK-only booking, 15% delivered outside the UK, counts agreed
This came out of the makegoods thread in the AdCP Slack, suggested by [person_y] with broadcast TV input from [person_x]. Can this RFC's dispute lifecycle carry a delivery finding when buyer and seller agree on the counts?
VARIANCE_EXCEEDEDonly fires when counts disagree, so this case shows whether the lifecycle is limited to counts or can carry other findings.The test keeps three things as separate records: the finding (package, reporting period, evidence), the seller's remedy offer, and the buyer's acceptance or dispute. It also asserts that the finding alone does not change the invoice.
The spec references below are AdCP 3.2, build 3.2.8. The figures are made up for the example.
Agreed terms
One package, priced at a £10 CPM with a £50,000 budget (5,000,000 impressions). The seller's ad server is the billing count.
Steps
1. Delivery is reported.
get_media_buy_deliveryreturns a finalby_packagerow with a country-levelby_geobreakdown (trimmed):3.2.8: ✅ The delivery report already shows the problem: 750,000 impressions (£7,500) served outside
geo_countries. I've assumed country-levelgeo_codeuses ISO 3166-1 alpha-2, asgeo_countriesdoes.2. Counts are reconciled. The buyer's ad server counts 4,985,000 impressions, 0.3% below the seller and well inside the 10% tolerance.
3.2.8 / this RFC: Every signal is green.
VARIANCE_EXCEEDED.sync_reporting_status:received. None of thecontent_mismatchcodes apply (scope_media_buy_missing,coverage_short,metric_missing,schema_nonconformant,currency_mismatch,period_mismatch). The feed matches what was agreed; the delivery doesn't.geo_distributionshowing IE and FR can be denied, and the seller pauses. That stops further delivery, but nothing is recorded about the 750,000 impressions already served. Governance is also explicitly not the billing source of truth.This is the same failure shape as the RFC's own scenario: every signal green, and the dispute moves to email.
3. A finding is recorded. Either party opens it. It needs:
media_buy_id,package_idreporting_periodtargeting_overlay.geo_countriesby_georows, bound by their revision content hash3.2.8: ❌ There is nowhere to record this. The lifecycle on
reporting-status-issue.json(issue_state:open,acknowledged,resolved,waived) is the closest shape, but its codes cover reporting faults, and this RFC's new codes cover count variance only.4. The invoice. The finding by itself changes nothing. The seller invoices from the
is_finalrows as usual.3.2.8:⚠️ Nothing says whether the affected volume (£7,500) is invoiced as normal or held while a finding is open. This needs a stated rule either way. Governance's adjustment ledger is a useful precedent: a reported adjustment changes nothing until the buyer accepts it.
5. The seller offers a remedy. This is a separate record that references the finding, chosen from
makegood_policy. For example,additional_deliveryof 750,000 UK impressions within 14 days, orinvoice_adjustmentof £7,500.3.2.8: ❌ There is no message for it. The billing-authority page lists
seller_proposed_adjustmentamong the states of a future dispute task, but 3.2 doesn't define that task.6. The buyer accepts or disputes. This is also a separate record, referencing the offer. Where the agreed terms already fix the remedy, acceptance could follow those terms rather than need its own step.
3.2.8: ❌ This happens out of band today.
7. The remedy is fulfilled and the finding closed. The record carries completion evidence (make-good delivery rows, or a credit note reference) and the finding moves to
resolved.3.2.8:⚠️
report_plan_adjustment(adjustment_type: "makegood") can record the outcome, but only for buys under campaign governance, which is experimental.Result
Questions for the WG
reporting-status-issue.jsonmeant for any delivery finding, or for count disagreements only?VARIANCE_EXCEEDED, a reference to the breached term, and remedy offer and response records that point to the finding.Out of scope on purpose: how a platform detects a breach, how a remedy is fulfilled, and who bears the cost. All three are left to the platforms and the commercial terms.
The over-delivery case (a £50,000 package delivering £56,000) can be run through the same template next. It adds one requirement: separating delivered, billable and disputed volume, which
<details> <summary>Spec pages referenced (3.2.8)</summary>get_media_buy_deliverydoesn't do today.- Targeting
- get_media_buy_delivery · geo-delivery-metrics.json
- sync_reporting_status
- Billing authority · measurement-terms.json
- Campaign governance · report_plan_adjustment
</details>## Worked example: a UK-only booking, 15% delivered outside the UK, counts agreedThis came out of the makegoods thread in the AdCP Slack, suggested by [person_y] with broadcast TV input from [person_x]. Can this RFC's dispute lifecycle carry a delivery finding when buyer and seller agree on the counts?
VARIANCE_EXCEEDEDonly fires when counts disagree, so this case shows whether the lifecycle is limited to counts or can carry other findings.The test keeps three things as separate records: the finding (package, reporting period, evidence), the seller's remedy offer, and the buyer's acceptance or dispute. It also asserts that the finding alone does not change the invoice.
The spec references below are AdCP 3.2, build 3.2.8. The figures are made up for the example.
Agreed terms
One package, priced at a £10 CPM with a £50,000 budget (5,000,000 impressions). The seller's ad server is the billing count.
{ "targeting_overlay": { "geo_countries": ["GB"] }, "measurement_terms": { "billing_measurement": { "vendor": { "domain": "seller-adserver.example" }, "max_variance_percent": 10 }, "makegood_policy": { "available_remedies": ["additional_delivery", "credit", "invoice_adjustment"] } } }Steps
1. Delivery is reported.
get_media_buy_deliveryreturns a finalby_packagerow with a country-levelby_geobreakdown (trimmed):{ "package_id": "pkg_uk_01", "pricing_model": "cpm", "rate": 10, "currency": "GBP", "impressions": 5000000, "spend": 50000, "is_final": true, "by_geo": [ { "geo_level": "country", "geo_code": "GB", "impressions": 4250000, "spend": 42500 }, { "geo_level": "country", "geo_code": "IE", "impressions": 450000, "spend": 4500 }, { "geo_level": "country", "geo_code": "FR", "impressions": 300000, "spend": 3000 } ] }3.2.8: ✅ The delivery report already shows the problem: 750,000 impressions (£7,500) served outside
geo_countries. I've assumed country-levelgeo_codeuses ISO 3166-1 alpha-2, asgeo_countriesdoes.2. Counts are reconciled. The buyer's ad server counts 4,985,000 impressions, 0.3% below the seller and well inside the 10% tolerance.
3.2.8 / this RFC: Every signal is green.
VARIANCE_EXCEEDED.sync_reporting_status:received. None of thecontent_mismatchcodes apply (scope_media_buy_missing,coverage_short,metric_missing,schema_nonconformant,currency_mismatch,period_mismatch). The feed matches what was agreed; the delivery doesn't.geo_distributionshowing IE and FR can be denied, and the seller pauses. That stops further delivery, but nothing is recorded about the 750,000 impressions already served. Governance is also explicitly not the billing source of truth.This is the same failure shape as the RFC's own scenario: every signal green, and the dispute moves to email.
3. A finding is recorded. Either party opens it. It needs:
media_buy_id,package_idreporting_periodtargeting_overlay.geo_countriesby_georows, bound by their revision content hash3.2.8: ❌ There is nowhere to record this. The lifecycle on
reporting-status-issue.json(issue_state:open,acknowledged,resolved,waived) is the closest shape, but its codes cover reporting faults, and this RFC's new codes cover count variance only.4. The invoice. The finding by itself changes nothing. The seller invoices from the
is_finalrows as usual.3.2.8:⚠️ Nothing says whether the affected volume (£7,500) is invoiced as normal or held while a finding is open. This needs a stated rule either way. Governance's adjustment ledger is a useful precedent: a reported adjustment changes nothing until the buyer accepts it.
5. The seller offers a remedy. This is a separate record that references the finding, chosen from
makegood_policy. For example,additional_deliveryof 750,000 UK impressions within 14 days, orinvoice_adjustmentof £7,500.3.2.8: ❌ There is no message for it. The billing-authority page lists
seller_proposed_adjustmentamong the states of a future dispute task, but 3.2 doesn't define that task.6. The buyer accepts or disputes. This is also a separate record, referencing the offer. Where the agreed terms already fix the remedy, acceptance could follow those terms rather than need its own step.
3.2.8: ❌ This happens out of band today.
7. The remedy is fulfilled and the finding closed. The record carries completion evidence (make-good delivery rows, or a credit note reference) and the finding moves to
resolved.3.2.8:⚠️
report_plan_adjustment(adjustment_type: "makegood") can record the outcome, but only for buys under campaign governance, which is experimental.Result
by_geoVARIANCE_EXCEEDEDcarries the remedy menu, but no offerQuestions for the WG
reporting-status-issue.jsonmeant for any delivery finding, or for count disagreements only?VARIANCE_EXCEEDED, a reference to the breached term, and remedy offer and response records that point to the finding.Out of scope on purpose: how a platform detects a breach, how a remedy is fulfilled, and who bears the cost. All three are left to the platforms and the commercial terms.
The over-delivery case (a £50,000 package delivering £56,000) can be run through the same template next. It adds one requirement: separating delivered, billable and disputed volume, which
get_media_buy_deliverydoesn't do today.Spec pages referenced (3.2.8)