Interface ReportPlanOutcomeRequest

Report the outcome of an action to the governance agent. Called by the orchestrator (buyer-side agent) after a seller responds. The authenticated reporter must match the caller on the original approved intent, purchase_type must match that intent, and only one terminal settlement is allowed across all lifecycle checks sharing the opaque action binding. This is the 'after' half of the governance loop. Sellers do not call this task -- they report delivery data via check_governance with phase 'delivery'.

interface ReportPlanOutcomeRequest {
    adcp_version?: string;
    adcp_major_version?: number;
    plan_id: string;
    check_id?: string;
    idempotency_key: string;
    purchase_type?: PurchaseType;
    outcome: OutcomeType;
    seller_response?: {
        seller_reference?: string;
        committed_budget?: number;
        packages?: { budget?: number }[];
        planned_delivery?: {
            media_buy_id?: string;
            proposal_id?: string;
            proposal_terms_digest?: string;
            geo?: { countries?: string[]; regions?: string[] };
            channels?: MediaChannel[];
            start_time?: string;
            end_time?: string;
            frequency_cap?: {
                suppress?: Duration;
                suppress_minutes?: number;
                max_impressions?: number;
                per?: ReachUnit;
                window?: Duration;
            };
            audience_summary?: string;
            audience_targeting?: [AudienceSelector, ...AudienceSelector[]];
            total_budget?: number;
            daily_budget_cap?: number;
            budget_cap_timezone?: string;
            currency?: string;
            budget_allocation?: BudgetAllocation;
            pacing?: Pacing;
            bidding?: {
                automatic?: true;
                bid_amount?: number;
                max_bid?: number;
                cost_per?: { amount: number; strength: "cap" | "target" };
                roas?: { value: number; strength: "target" | "floor" };
            };
            enforced_policies?: string[];
            ext?: ExtensionObject;
        };
        creative_deadline?: string;
    };
    delivery?: | {
        observation_id: string;
        source: "seller_statement_copy";
        observed_at: string;
        seller_statement_id: string;
        seller_statement_digest: string;
        reporting_period: { start: string; end: string };
        cumulative_spend: number;
        currency: string;
        period_closed?: boolean;
        impressions?: number;
    }
    | {
        observation_id: string;
        source: "buyer_measurement";
        observed_at: string;
        seller_statement_id?: string;
        seller_statement_digest?: string;
        reporting_period: { start: string; end: string };
        cumulative_spend: number;
        currency: string;
        period_closed?: boolean;
        impressions?: number;
    };
    error?: { code?: string; message?: string };
    governance_context?: string;
    context?: ContextObject;
    ext?: ExtensionObject;
}

Index

Properties

adcp_version? adcp_major_version? plan_id check_id? idempotency_key purchase_type? outcome seller_response? delivery? error? governance_context? context? ext?

Properties

`Optional`adcp_version

adcp_version?: string

Release-precision AdCP version (VERSION.RELEASE, e.g. "3.0", "3.1", "3.1-beta"). On a request: the buyer's release pin — the seller validates against its supported_versions and returns VERSION_UNSUPPORTED on cross-major mismatch, or downshifts to the highest supported release within the same major. On a response: the release the seller actually served — clients SHOULD validate the response against that release's schema, not against their pin. Patches are not negotiated; surface them as build_version on capabilities for operational visibility. When omitted, falls back to adcp_major_version (deprecated) or server default. Buyers SHOULD emit both adcp_version and adcp_major_version through 3.x to remain compatible with sellers that only read the legacy field. NORMALIZATION: SDKs that read full-semver values from bundle metadata (e.g. ComplianceIndex.published_version = "3.1.0-beta.1") MUST normalize to release-precision ("3.1-beta.1") before emitting on the wire — meta-field values are NOT valid wire values.

`Optional`adcp_major_version

adcp_major_version?: number

Deprecated

DEPRECATED in favor of adcp_version (release-precision string). Servers MUST continue to honor this field through 3.x. Removed in 4.0. Original semantics: the AdCP major version the buyer's payloads conform to. Sellers validate against their supported major_versions and return VERSION_UNSUPPORTED if unsupported. When omitted, the seller assumes its highest supported version.

plan_id

plan_id: string

The plan this outcome is for. The plan is owned by the authenticated buyer that synchronized it; plan_id is an identifier, not an account credential. Completed and failed settlements inherit their commercial binding from the exact approved check tuple.

`Optional`check_id

check_id?: string

The check_id from check_governance. Required for completed and failed outcomes and for buyer delivery observations. A delivery observation names the exact seller delivery check whose canonical statement is being compared.

idempotency_key

idempotency_key: string

Buyer-generated unique key for this outcome report. An identical retry returns the cached response without another settlement; reuse with a different canonical payload returns IDEMPOTENCY_CONFLICT. Use a fresh UUID v4 for each distinct report.

Min Length

Max Length

255

Pattern

^[A-Za-z0-9_.:-]{16,255}$

`Optional`purchase_type

purchase_type?: PurchaseType

outcome

outcome: OutcomeType

`Optional`seller_response

seller_response?: {
    seller_reference?: string;
    committed_budget?: number;
    packages?: { budget?: number }[];
    planned_delivery?: {
        media_buy_id?: string;
        proposal_id?: string;
        proposal_terms_digest?: string;
        geo?: { countries?: string[]; regions?: string[] };
        channels?: MediaChannel[];
        start_time?: string;
        end_time?: string;
        frequency_cap?: {
            suppress?: Duration;
            suppress_minutes?: number;
            max_impressions?: number;
            per?: ReachUnit;
            window?: Duration;
        };
        audience_summary?: string;
        audience_targeting?: [AudienceSelector, ...AudienceSelector[]];
        total_budget?: number;
        daily_budget_cap?: number;
        budget_cap_timezone?: string;
        currency?: string;
        budget_allocation?: BudgetAllocation;
        pacing?: Pacing;
        bidding?: {
            automatic?: true;
            bid_amount?: number;
            max_bid?: number;
            cost_per?: { amount: number; strength: "cap" | "target" };
            roas?: { value: number; strength: "target" | "floor" };
        };
        enforced_policies?: string[];
        ext?: ExtensionObject;
    };
    creative_deadline?: string;
}

The seller's full response. Required when outcome is 'completed'.

Type Declaration

Optionalseller_reference?: string
The seller's identifier for the created resource (e.g., media_buy_id, rights_grant_id, deployment_id). Not interpreted by the governance agent — included in audit logs for human-readable traceability alongside the opaque governance_context.

Max Length
255
Optionalcommitted_budget?: number
Buyer-reported seller amount retained for reconciliation and audit. It is never ledger authority: the governance agent derives the reserved commitment from its own approved intent check, or from the matching purchase execution check when one exists. A report above that authorized amount is rejected; a lower report does not restore headroom.

Minimum
0
Optionalpackages?: { budget?: number }[]
Confirmed packages with actual budget and targeting.
Optionalplanned_delivery?: {
    media_buy_id?: string;
    proposal_id?: string;
    proposal_terms_digest?: string;
    geo?: { countries?: string[]; regions?: string[] };
    channels?: MediaChannel[];
    start_time?: string;
    end_time?: string;
    frequency_cap?: {
        suppress?: Duration;
        suppress_minutes?: number;
        max_impressions?: number;
        per?: ReachUnit;
        window?: Duration;
    };
    audience_summary?: string;
    audience_targeting?: [AudienceSelector, ...AudienceSelector[]];
    total_budget?: number;
    daily_budget_cap?: number;
    budget_cap_timezone?: string;
    currency?: string;
    budget_allocation?: BudgetAllocation;
    pacing?: Pacing;
    bidding?: {
        automatic?: true;
        bid_amount?: number;
        max_bid?: number;
        cost_per?: { amount: number; strength: "cap" | "target" };
        roas?: { value: number; strength: "target" | "floor" };
    };
    enforced_policies?: string[];
    ext?: ExtensionObject;
}
- Optionalmedia_buy_id?: string
  Seller-assigned media buy identifier. Optional on a purchase-phase prepare/check because the service may not assign the identifier until commit; required on modification and delivery lifecycle checks.
- Optionalproposal_id?: string
  Proposal snapshot being executed or currently governing the MediaBuy.
- Optionalproposal_terms_digest?: string
  Digest of the proposal commercial_terms. The governance agent compares it to the digest bound during the intent check.
- Optionalgeo?: { countries?: string[]; regions?: string[] }
  Geographic targeting the seller will apply.
  - Optionalcountries?: string[]
    ISO 3166-1 alpha-2 country codes where ads will deliver.
  - Optionalregions?: string[]
    ISO 3166-2 subdivision codes where ads will deliver.
- Optionalchannels?: MediaChannel[]
  Channels the seller will deliver on.
- Optionalstart_time?: string
  Actual flight start the seller will use.
- Optionalend_time?: string
  Actual flight end the seller will use.
- Optionalfrequency_cap?: {
      suppress?: Duration;
      suppress_minutes?: number;
      max_impressions?: number;
      per?: ReachUnit;
      window?: Duration;
  }
  - Optionalsuppress?: Duration
    Cooldown period between consecutive exposures to the same entity. Prevents back-to-back ad delivery (e.g. {"interval": 60, "unit": "minutes"} for a 1-hour cooldown). Preferred over suppress_minutes.
  - Optionalsuppress_minutes?: number
    Deprecated
    Deprecated — use suppress instead. Cooldown period in minutes between consecutive exposures to the same entity (e.g. 60 for a 1-hour cooldown).
  - Optionalmax_impressions?: number
    Maximum number of impressions per entity per window. For duration windows, implementations typically use a rolling window; 'campaign' applies a fixed cap across the full flight.
  - Optionalper?: ReachUnit
    Entity granularity for impression counting. Required when max_impressions is set.
  - Optionalwindow?: Duration
    Time window for the max_impressions cap (e.g. {"interval": 7, "unit": "days"} or {"interval": 1, "unit": "campaign"} for the full flight). Required when max_impressions is set.
- Optionalaudience_summary?: string
  Human-readable summary of the audience the seller will target.
- Optionalaudience_targeting?: [AudienceSelector, ...AudienceSelector[]]
  Structured audience targeting the seller will activate. Each entry is either a signal reference or a descriptive criterion. When present, governance agents MUST use this for bias/fairness validation and SHOULD ignore audience_summary for validation purposes. The audience_summary field is a human-readable rendering of this array, not an independent declaration.
  
  Min Items
  1
- Optionaltotal_budget?: number
  Total budget the seller will deliver against.
- Optionaldaily_budget_cap?: number
  Hard aggregate daily spend ceiling the seller will enforce. Governance checks compare it with the authorized execution controls; it does not allocate spend to packages.
- Optionalbudget_cap_timezone?: string
  IANA timezone defining the calendar-day boundary for every daily cap on the planned media buy.
- Optionalcurrency?: string
  ISO 4217 currency code for the budget. Governance execution checks require it whenever total_budget is present and require it to match the intent-authorized currency.
- Optionalbudget_allocation?: BudgetAllocation
  Seller-accepted cross-package allocation authority and goals. Presence with seller_optimized mode means automatic within-buy reallocations are part of the committed delivery, not separate modification actions.
- Optionalpacing?: Pacing
- Optionalbidding?: {
      automatic?: true;
      bid_amount?: number;
      max_bid?: number;
      cost_per?: { amount: number; strength: "cap" | "target" };
      roas?: { value: number; strength: "target" | "floor" };
  }
  Seller-interpreted media-buy bidding policy used for governance and delivery transparency. Goal-bound controls follow budget-allocation scope semantics and monetary fields use the planned delivery currency. Package-authored overrides, including explicit automatic overrides, remain on packages rather than being copied into this aggregate field.
  - Optionalautomatic?: true
    Explicitly use seller/provider automatic bidding at this authored scope. At package scope this is a complete override of a media-buy policy, not inheritance. It MUST be the only field in the block and MUST be preserved on readback.
  - Optionalbid_amount?: number
    Manual auction bid denominated in the media-buy currency and expressed per the selected pricing option's auction unit. For example, a CPM option interprets the amount per thousand impressions. This is the amount submitted to the auction, not a promise that the clearing price equals it. Requires an auction-priced pricing option whose currency equals the media-buy currency.
  - Optionalmax_bid?: number
    Hard per-auction ceiling denominated in the media-buy currency and expressed per the selected pricing option's auction unit. This is the only canonical hard auction ceiling and MUST NOT be translated into an average outcome-cost control. Requires an auction-priced pricing option whose currency equals the media-buy currency. May stand alone or supplement cost_per/roas only when the relevant scope capability advertises that combination.
  - Optionalcost_per?: { amount: number; strength: "cap" | "target" }
    Average cost control per result of the scope-bound primary optimization goal. At seller-optimized media-buy scope it binds to budget_allocation.optimization_goals; at package scope it binds to that package's optimization_goals; at fixed media-buy scope it binds independently to each inheriting package and is valid only when their primary-goal result units are compatible. Metric goals are compatible only when metric and every result-defining qualifier match; vendor_metric goals only when vendor and metric_id match; event goals only when the event_type/custom_event_name set and resolved attribution_window match. Primary is the earliest array entry among goals tied for the lowest explicit numeric priority; unprioritized goals follow explicitly prioritized goals; when all priorities are absent, the first entry is primary.
    - amount: number
      Average cost amount per scope-bound primary-goal result, denominated in the media-buy currency.
    - strength: "cap" | "target"
      cap optimizes for an average at or below the amount and accepts underdelivery when necessary; target optimizes around the amount while balancing volume and spend. Neither is a per-result or per-auction guarantee.
  - Optionalroas?: { value: number; strength: "target" | "floor" }
    Dimensionless return-on-ad-spend control bound to the same scope-specific primary goal rules as cost_per. The bound goal must be value-bearing; a fixed media-buy default requires a value-bearing primary goal on every inheriting package. Every referenced value-bearing event source MUST declare value_currencies containing the media-buy currency. The seller validates this at buy creation; each buy consumes only exact-currency records, while other declared currencies remain available to other buys. Sellers MUST NOT perform currency conversion.
    - value: number
      Return per unit of ad spend; 4 means 4 units of value per 1 unit spent.
    - strength: "target" | "floor"
      floor prefers underdelivery to knowingly optimizing below the requested return; target optimizes around the requested return. Neither guarantees realized return.
- Optionalenforced_policies?: string[]
  Registry policy IDs the seller will enforce for this delivery.
- Optionalext?: ExtensionObject
Optionalcreative_deadline?: string
ISO 8601 deadline for creative submission.

Format
date-time

`Optional`delivery

delivery?:
    | {
        observation_id: string;
        source: "seller_statement_copy";
        observed_at: string;
        seller_statement_id: string;
        seller_statement_digest: string;
        reporting_period: { start: string; end: string };
        cumulative_spend: number;
        currency: string;
        period_closed?: boolean;
        impressions?: number;
    }
    | {
        observation_id: string;
        source: "buyer_measurement";
        observed_at: string;
        seller_statement_id?: string;
        seller_statement_digest?: string;
        reporting_period: { start: string; end: string };
        cumulative_spend: number;
        currency: string;
        period_closed?: boolean;
        impressions?: number;
    }

Buyer-attributed observation compared with the canonical seller delivery statement identified by check_id. This evidence never overwrites seller evidence or creates a second commitment. A conflict produces an explicit disputed reconciliation state while the operational period is open; the plan owner may close it without asserting final billing truth.

Type Declaration

{
    observation_id: string;
    source: "seller_statement_copy";
    observed_at: string;
    seller_statement_id: string;
    seller_statement_digest: string;
    reporting_period: { start: string; end: string };
    cumulative_spend: number;
    currency: string;
    period_closed?: boolean;
    impressions?: number;
}
- observation_id: string
  Stable buyer-issued identifier for this observation.
  
  Min Length
  1
  
  Max Length
  255
- source: "seller_statement_copy"
  Whether the buyer is forwarding the seller statement it received or reporting an independently measured observation. A forwarded seller statement is not independent evidence.
- observed_at: string
  Format
  date-time
- seller_statement_id: string
  Seller statement identifier as received by the buyer. Required for seller_statement_copy.
- seller_statement_digest: string
  Digest received with the seller statement. Governance compares it to the seller-authenticated canonical digest.
  
  Pattern
  ^sha256:[a-f0-9]{64}$
- reporting_period: { start: string; end: string }
  Start and end timestamps for the reporting window.
  - start: string
    Format
    date-time
  - end: string
    Format
    date-time
- cumulative_spend: number
  Buyer-attributed cumulative spend for the governed action.
  
  Minimum
  0
- currency: string
  Pattern
  ^[A-Z]{3}$
- Optionalperiod_closed?: boolean
  Buyer-declared operational closure of this governance reporting period. When true, governance freezes the period after recording this observation. An unresolved mismatch becomes closed_unresolved and no longer blocks later governance. Closure is not final billing or commercial settlement. Only the authenticated plan owner may set this to true; the governance agent MUST reject it from any other authenticated reporter.
- Optionalimpressions?: number
  Minimum
  0
{
    observation_id: string;
    source: "buyer_measurement";
    observed_at: string;
    seller_statement_id?: string;
    seller_statement_digest?: string;
    reporting_period: { start: string; end: string };
    cumulative_spend: number;
    currency: string;
    period_closed?: boolean;
    impressions?: number;
}
- observation_id: string
  Stable buyer-issued identifier for this observation.
  
  Min Length
  1
  
  Max Length
  255
- source: "buyer_measurement"
  Whether the buyer is forwarding the seller statement it received or reporting an independently measured observation. A forwarded seller statement is not independent evidence.
- observed_at: string
  Format
  date-time
- Optionalseller_statement_id?: string
  Seller statement identifier as received by the buyer. Required for seller_statement_copy.
- Optionalseller_statement_digest?: string
  Digest received with the seller statement. Governance compares it to the seller-authenticated canonical digest.
  
  Pattern
  ^sha256:[a-f0-9]{64}$
- reporting_period: { start: string; end: string }
  Start and end timestamps for the reporting window.
  - start: string
    Format
    date-time
  - end: string
    Format
    date-time
- cumulative_spend: number
  Buyer-attributed cumulative spend for the governed action.
  
  Minimum
  0
- currency: string
  Pattern
  ^[A-Z]{3}$
- Optionalperiod_closed?: boolean
  Buyer-declared operational closure of this governance reporting period. When true, governance freezes the period after recording this observation. An unresolved mismatch becomes closed_unresolved and no longer blocks later governance. Closure is not final billing or commercial settlement. Only the authenticated plan owner may set this to true; the governance agent MUST reject it from any other authenticated reporter.
- Optionalimpressions?: number
  Minimum
  0

`Optional`error

error?: { code?: string; message?: string }

Error details. Required when outcome is 'failed'.

Type Declaration

Optionalcode?: string
Error code from the seller.
Optionalmessage?: string
Human-readable error description.

`Optional`governance_context

governance_context?: string

Opaque governance context from the check_governance response. Required with check_id for completed and failed outcomes and buyer delivery observations.

Min Length

Max Length

4096

Pattern

^[\x20-\x7E]+$

`Optional`context

context?: ContextObject

`Optional`ext

ext?: ExtensionObject

Interface ReportPlanOutcomeRequest

Index

Properties

Properties

Optionaladcp_version

Optionaladcp_major_version

Deprecated

plan_id

Optionalcheck_id

idempotency_key

Min Length

Max Length

Pattern

Optionalpurchase_type

outcome

Optionalseller_response

Type Declaration

Optionalseller_reference?: string

Max Length

Optionalcommitted_budget?: number

Minimum

Optionalpackages?: { budget?: number }[]

Optionalmedia_buy_id?: string

Optionalproposal_id?: string

Optionalproposal_terms_digest?: string

Optionalgeo?: { countries?: string[]; regions?: string[] }

Optionalcountries?: string[]

Optionalregions?: string[]

Optionalchannels?: MediaChannel[]

Optionalstart_time?: string

Optionalend_time?: string

Optionalfrequency_cap?: { suppress?: Duration; suppress_minutes?: number; max_impressions?: number; per?: ReachUnit; window?: Duration;}

Optionalsuppress?: Duration

Optionalsuppress_minutes?: number

Deprecated

Optionalmax_impressions?: number

Optionalper?: ReachUnit

Optionalwindow?: Duration

Optionalaudience_summary?: string

Optionalaudience_targeting?: [AudienceSelector, ...AudienceSelector[]]

Min Items

Optionaltotal_budget?: number

Optionaldaily_budget_cap?: number

Optionalbudget_cap_timezone?: string

Optionalcurrency?: string

Optionalbudget_allocation?: BudgetAllocation

Optionalpacing?: Pacing

Optionalbidding?: { automatic?: true; bid_amount?: number; max_bid?: number; cost_per?: { amount: number; strength: "cap" | "target" }; roas?: { value: number; strength: "target" | "floor" };}

Optionalautomatic?: true

Optionalbid_amount?: number

Optionalmax_bid?: number

Optionalcost_per?: { amount: number; strength: "cap" | "target" }

amount: number

strength: "cap" | "target"

Optionalroas?: { value: number; strength: "target" | "floor" }

value: number

strength: "target" | "floor"

Optionalenforced_policies?: string[]

Optionalext?: ExtensionObject

Optionalcreative_deadline?: string

Format

Optionaldelivery

Type Declaration

observation_id: string

Min Length

Max Length

source: "seller_statement_copy"

observed_at: string

Format

seller_statement_id: string

seller_statement_digest: string

Pattern

reporting_period: { start: string; end: string }

start: string

Format

end: string

Format

cumulative_spend: number

Minimum

currency: string

`Optional`adcp_version

`Optional`adcp_major_version

`Optional`check_id

`Optional`purchase_type

`Optional`seller_response

`Optional`seller_reference?: string

`Optional`committed_budget?: number

`Optional`packages?: { budget?: number }[]

`Optional`media_buy_id?: string

`Optional`proposal_id?: string

`Optional`proposal_terms_digest?: string

`Optional`geo?: { countries?: string[]; regions?: string[] }

`Optional`countries?: string[]

`Optional`regions?: string[]

`Optional`channels?: MediaChannel[]

`Optional`start_time?: string

`Optional`end_time?: string

`Optional`frequency_cap?: {
suppress?: Duration;
suppress_minutes?: number;
max_impressions?: number;
per?: ReachUnit;
window?: Duration;
}

`Optional`suppress?: Duration

`Optional`suppress_minutes?: number

`Optional`max_impressions?: number

`Optional`per?: ReachUnit

`Optional`window?: Duration

`Optional`audience_summary?: string

`Optional`audience_targeting?: [AudienceSelector, ...AudienceSelector[]]

`Optional`total_budget?: number

`Optional`daily_budget_cap?: number

`Optional`budget_cap_timezone?: string

`Optional`currency?: string

`Optional`budget_allocation?: BudgetAllocation

`Optional`pacing?: Pacing

`Optional`bidding?: {
automatic?: true;
bid_amount?: number;
max_bid?: number;
cost_per?: { amount: number; strength: "cap" | "target" };
roas?: { value: number; strength: "target" | "floor" };
}

`Optional`automatic?: true

`Optional`bid_amount?: number

`Optional`max_bid?: number

`Optional`cost_per?: { amount: number; strength: "cap" | "target" }

`Optional`roas?: { value: number; strength: "target" | "floor" }

`Optional`enforced_policies?: string[]

`Optional`ext?: ExtensionObject

`Optional`creative_deadline?: string

`Optional`delivery

`Optional`period_closed?: boolean

`Optional`impressions?: number

`Optional`seller_statement_id?: string

`Optional`seller_statement_digest?: string

`Optional`period_closed?: boolean

`Optional`impressions?: number

`Optional`error

`Optional`code?: string

`Optional`message?: string

`Optional`governance_context

`Optional`context

`Optional`ext