Skip to content

RFC: unify Reliable Reporting with billing authority — reserve authoritative_party now, buyer-deposited billing revisions in 3.3 #7440

Open

Description

@bokelley

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:

  1. core/reporting-delivery-config.json allOf: feed_purpose: billing forces reconciliation_mode: consumer_receipt, which forces method. A Core-tier buyer-basis billing feed is schema-illegal.
  2. core/reporting-consumer-status.json attribution text: consumer submissions "never overwrite or become authoritative … revision … evidence".
  3. core/reporting-reliability-statistics.json, production_status, and revision_count assume 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[], bounded reporting_rows[], revision_content_sha256 over the same JCS binding Core already uses
  • source as a BrandRef matching billing_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_EXCEEDED carrying both values, the threshold, and the makegood_policy remedy 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_party reserved in reporting-delivery-config.json with the allOf relaxation and consumer-status carve-out, before the Core requirement lands
  • sync_reporting_revisions request/response schemas, reporting-consumer-revision.json, VARIANCE_EXCEEDED and CONSUMER_REVISION_OVERDUE issue codes
  • Core guide and billing-authority doc cross-reference each other; report_usage media-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

🤖 Generated with Claude Code

Activity

  1. added
    claude-triagingTriage routine is actively working on this issue (1-3 min)
    on Sep 13, 2026
  2. bokelley commented on Sep 13, 2026

    @bokelley
    ContributorAuthor

    Triage

    Classification: RFC — protocol change proposal
    Bucket(s): spec / protocol, media-buy, rfc
    Status: ready-for-human

    What the experts said:

    • ad-tech-protocol-expert: Schema illegality claim holds — billing-feed allOf makes buyer-basis Core configs schema-invalid today (feed_purpose: billing → reconciliation_mode: consumer_receipt → method required, but Core omits method). 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_revisions vs. existing report_usage coexistence needs a precedence rule before 3.3 can land safely.
    • ad-tech-protocol-expert-deep: authoritative_party on the delivery config can conflict with billing_measurement.vendor on the package — a buyer could set authoritative_party: consumer on a config for a deal whose vendor names the seller's ad server. Better placement: on measurement_terms at deal time. The allOf relaxation as written could silently allow receipt-free seller-authoritative billing, which is a behavioral regression. reporting-consumer-status.json does 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_party placement, (b) new task vs. receipt extension, (c) authorization boundary for buyer deposit.
    • adtech-product-expert: report_usage retirement 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: extend sync_reporting_receipts with revision_type: buyer_deposited — health states and variance checks attach to the existing receipt/ledger surface without a parallel state machine. The authoritative_party reservation is a convenience, not a correctness requirement on an experimental surface (could patch after sync_reporting_status ships).

    My take: The gap is real — billing-authority.mdx line 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_party live?

    Option A — on the delivery config (RFC's proposal). Keeps billing basis at the reporting layer; risk of conflict with billing_measurement.vendor on the package.

    {
      "delivery_config_id": "cfg_billing_q3",
      "feed_purpose": "billing",
      "authoritative_party": "consumer",
      "reconciliation_mode": "consumer_receipt"
    }

    Option B — on measurement_terms at deal time (eliminates dual-encoding conflict; config derives the value from the package). Requires config-level logic to read billing_measurement.vendor rather 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_revisions task (RFC's proposal). Parallel buyer→seller push; CONSUMER_REVISION_OVERDUE is 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_receipts with revision_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):

    1. reporting-consumer-status.json is 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.
    2. report_usage retirement notice must be scoped to media_buy_id records where billing_measurement.vendor names the caller as billing basis — not the full task.
    3. Precedence rule required: what wins when authoritative_party: consumer is set on a config but billing_measurement.vendor names the seller's ad server?

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


    Generated by Claude Code

  3. added
    rfcProtocol change — auto-adds to roadmap board
    claude-triagedIssue has been triaged by the Claude Code triage routine. Remove to re-triage.
    needs-wg-reviewBlocked on a working-group decision — surface in WG meeting agendas
    media-buyIssue concerns the media-buy protocol domain
    and removed
    claude-triagingTriage routine is actively working on this issue (1-3 min)
    on Sep 13, 2026
  4. added this to the Spec Backlog milestone on Sep 13, 2026
  5. lukasz-pubx commented on Nov 17, 2026

    @lukasz-pubx
    Contributor

    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_EXCEEDED only 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_delivery returns a final by_package row with a country-level by_geo breakdown (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-level geo_code uses ISO 3166-1 alpha-2, as geo_countries does.

    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.

    • This RFC: within tolerance, so the obligation is satisfied and invoicing proceeds. No VARIANCE_EXCEEDED.
    • sync_reporting_status: received. None of the content_mismatch codes 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.
    • Campaign governance: if the buy is governed, a delivery check with geo_distribution showing 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_id
    • reporting_period
    • the term breached: targeting_overlay.geo_countries
    • evidence: the final revision's by_geo rows, bound by their revision content hash
    • affected volume: 750,000 impressions / £7,500

    3.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_final rows 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_delivery of 750,000 UK impressions within 14 days, or invoice_adjustment of £7,500.

    3.2.8: ❌ There is no message for it. The billing-authority page lists seller_proposed_adjustment among 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

    Step Needed 3.2.8 today This RFC as proposed
    1. Report delivery | Breakdown by country | ✅ by_geo | n/a
    2. Reconcile counts | Counts agree | ✅ green everywhere | ✅ within tolerance, no issue raised
    3. Record finding | Package, period, term, evidence, volume | ❌ | ❌ count variance only
    4. Invoice | Finding alone changes nothing; rule for open findings | ⚠️ unstated | ⚠️ unstated
    5. Remedy offer | Seller offer referencing the finding | ❌ | ⚠️ VARIANCE_EXCEEDED carries the remedy menu, but no offer
    6. Accept or dispute | Buyer response referencing the offer | ❌ | ❌
    7. Fulfil and close | Completion evidence, finding resolved | ⚠️ governance only | ❌

    Questions for the WG

    1. Scope. Is the dispute lifecycle proposed for reporting-status-issue.json meant for any delivery finding, or for count disagreements only?
      • If any finding, it needs a finding type beyond VARIANCE_EXCEEDED, a reference to the breached term, and remedy offer and response records that point to the finding.
      • If counts only, this case needs a narrow separate RFC limited to those three records and their states. I'm happy to write it.
    2. Invoicing while a finding is open. Is the affected volume invoiced as normal or held?
    3. Pre-agreed remedies. Where the terms fix the remedy in advance, does the buyer's acceptance step drop out?

    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_delivery doesn't do today.

    <details> <summary>Spec pages referenced (3.2.8)</summary> </details>## 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_EXCEEDED only 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_delivery returns a final by_package row with a country-level by_geo breakdown (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-level geo_code uses ISO 3166-1 alpha-2, as geo_countries does.

    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.

    • This RFC: within tolerance, so the obligation is satisfied and invoicing proceeds. No VARIANCE_EXCEEDED.
    • sync_reporting_status: received. None of the content_mismatch codes 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.
    • Campaign governance: if the buy is governed, a delivery check with geo_distribution showing 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_id
    • reporting_period
    • the term breached: targeting_overlay.geo_countries
    • evidence: the final revision's by_geo rows, bound by their revision content hash
    • affected volume: 750,000 impressions / £7,500

    3.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_final rows 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_delivery of 750,000 UK impressions within 14 days, or invoice_adjustment of £7,500.

    3.2.8: ❌ There is no message for it. The billing-authority page lists seller_proposed_adjustment among 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

    Step Needed 3.2.8 today This RFC as proposed
    1. Report delivery Breakdown by country ✅ by_geo n/a
    2. Reconcile counts Counts agree ✅ green everywhere ✅ within tolerance, no issue raised
    3. Record finding Package, period, term, evidence, volume ❌ ❌ count variance only
    4. Invoice Finding alone changes nothing; rule for open findings ⚠️ unstated ⚠️ unstated
    5. Remedy offer Seller offer referencing the finding ❌ ⚠️ VARIANCE_EXCEEDED carries the remedy menu, but no offer
    6. Accept or dispute Buyer response referencing the offer ❌ ❌
    7. Fulfil and close Completion evidence, finding resolved ⚠️ governance only ❌

    Questions for the WG

    1. Scope. Is the dispute lifecycle proposed for reporting-status-issue.json meant for any delivery finding, or for count disagreements only?
      • If any finding, it needs a finding type beyond VARIANCE_EXCEEDED, a reference to the breached term, and remedy offer and response records that point to the finding.
      • If counts only, this case needs a narrow separate RFC limited to those three records and their states. I'm happy to write it.
    2. Invoicing while a finding is open. Is the affected volume invoiced as normal or held?
    3. Pre-agreed remedies. Where the terms fix the remedy in advance, does the buyer's acceptance step drop out?

    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_delivery doesn't do today.

    Spec pages referenced (3.2.8)
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 domainneeds-wg-reviewBlocked on a working-group decision — surface in WG meeting agendasrfcProtocol change — auto-adds to roadmap board

    Type

    No type

    Projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions