Interface ControlMediaBuyRequest

Apply revision-checked delivery controls or non-commercial metadata changes authorized by the MediaBuy's current available_actions[]. For a proposal-bound buy, the accepted envelope includes any applicable commercial_terms.change_terms[]: a self-serve control inside that term's typed constraints is already authorized. A control with no negotiated right returns ACTION_NOT_ALLOWED; a control that exercises an existing right outside its typed bounds returns REQUOTE_REQUIRED, after which the buyer can fork the accepted proposal through refine_proposals. Provide at least one control field. cancellation_reason requires canceled: true; cancellation is mutually exclusive with every other control. Creative mutation, new products/packages, flight changes, pricing changes, and billing-term changes are not accepted here.

interface ControlMediaBuyRequest {
    adcp_version?: string;
    adcp_major_version?: number;
    idempotency_key: string;
    account: CanonicalAccountReference;
    media_buy_id: string;
    revision: number;
    name?: string;
    paused?: boolean;
    canceled?: true;
    cancellation_reason?: string;
    total_budget?: { amount: number; currency: string };
    daily_budget_cap?: number | null;
    frequency_cap?:
        | {
            suppress?: Duration;
            suppress_minutes?: number;
            max_impressions?: number;
            per?: ReachUnit;
            window?: Duration;
        }
        | null;
    budget_cap_timezone?: string
    | null;
    budget_allocation?: CanonicalBudgetAllocation;
    pacing?: Pacing;
    bidding?:
        | {
            automatic?: true;
            bid_amount?: number;
            max_bid?: number;
            cost_per?: { amount: number; strength: "cap"
            | "target" };
            roas?: { value: number; strength: "target" | "floor" };
        }
        | null;
    packages?: {
        package_id: string;
        budget?: number
        | null;
        daily_budget_cap?: number | null;
        min_spend_target?: number | null;
        impressions?: number;
        pacing?: Pacing;
        bidding?:
            | {
                automatic?: true;
                bid_amount?: number;
                max_bid?: number;
                cost_per?: { amount: number; strength: "cap"
                | "target" };
                roas?: { value: number; strength: "target" | "floor" };
            }
            | null;
        paused?: boolean;
        canceled?: true;
        cancellation_reason?: string;
        targeting_overlay?: TargetingOverlayInput;
        catalog_ids?: [string, ...string[]];
        keyword_targets_add?: [KeywordTarget, ...KeywordTarget[]];
        keyword_targets_remove?: [KeywordTarget, ...KeywordTarget[]];
        negative_keywords_add?: [KeywordTarget, ...KeywordTarget[]];
        negative_keywords_remove?: [KeywordTarget, ...KeywordTarget[]];
        optimization_goals?: [
            CanonicalOptimizationGoal,
            ...CanonicalOptimizationGoal[],
        ];
    }[];
    reporting_webhook?: ReportingWebhook;
    governance_context?: string;
    push_notification_config?: PushNotificationConfig;
    context?: ContextObject;
    ext?: ExtensionObject;
}

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.

idempotency_key

idempotency_key: string

Min Length

Max Length

255

Pattern

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

account

account: CanonicalAccountReference

media_buy_id

media_buy_id: string

Min Length

revision

revision: number

Required optimistic-concurrency revision from the latest MediaBuy snapshot.

Minimum

Format

int

`Optional`name

name?: string

Replace the human-readable MediaBuy name as revision-checked operational metadata. This display label is not an identifier, financial reference, or change to the accepted commercial terms.

Min Length

Max Length

255

Pattern

`Optional`paused

paused?: boolean

`Optional`canceled

canceled?: true

Exercise an already-accepted unilateral cancellation right. A cancellation requiring seller agreement is requested by refining the accepted proposal.

`Optional`cancellation_reason

cancellation_reason?: string

Min Length

Max Length

500

`Optional`total_budget

total_budget?: { amount: number; currency: string }

Type Declaration

amount: number

Minimum
0
currency: string

Pattern
^[A-Z]{3}$

`Optional`daily_budget_cap

daily_budget_cap?: number | null

Replace the hard aggregate daily cap; null removes it. Numeric changes apply immediately with current-cap-day spend counted and do not redistribute purchase caps.

Minimum

`Optional`frequency_cap

frequency_cap?:
    | {
        suppress?: Duration;
        suppress_minutes?: number;
        max_impressions?: number;
        per?: ReachUnit;
        window?: Duration;
    }
    | null

Replace the shared MediaBuy frequency cap; null removes it. The change applies immediately without resetting counters: qualifying prior exposures still count in the resulting active window. Sellers MUST reject the complete mutation with UNSUPPORTED_FEATURE, before any change, if the cap is outside declared constraints or any active package cannot participate in the resulting shared counter, and MUST NOT clamp it. Requires update_media_buy_frequency_cap in available_actions.

Type Declaration

{
    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 across the owning field's full flight: the package flight for a targeting overlay, or the MediaBuy flight for a root cap.
- 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.
null

`Optional`budget_cap_timezone

budget_cap_timezone?: string | null

Replace the shared IANA cap-day timezone override; null restores the default selected by budget_capping.timezone_basis (Account.timezone or fixed_timezone). A timezone change begins at the next boundary under the previously effective timezone.

Min Length

`Optional`budget_allocation

budget_allocation?: CanonicalBudgetAllocation

`Optional`pacing

pacing?: Pacing

`Optional`bidding

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

Type Declaration

{
    automatic?: true;
    bid_amount?: number;
    max_bid?: number;
    cost_per?: { amount: number; strength: "cap" | "target" };
    roas?: { value: number; strength: "target" | "floor" };
}
- 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.
null

`Optional`packages

packages?: {
    package_id: string;
    budget?: number | null;
    daily_budget_cap?: number | null;
    min_spend_target?: number | null;
    impressions?: number;
    pacing?: Pacing;
    bidding?:
        | {
            automatic?: true;
            bid_amount?: number;
            max_bid?: number;
            cost_per?: { amount: number; strength: "cap"
            | "target" };
            roas?: { value: number; strength: "target" | "floor" };
        }
        | null;
    paused?: boolean;
    canceled?: true;
    cancellation_reason?: string;
    targeting_overlay?: TargetingOverlayInput;
    catalog_ids?: [string, ...string[]];
    keyword_targets_add?: [KeywordTarget, ...KeywordTarget[]];
    keyword_targets_remove?: [KeywordTarget, ...KeywordTarget[]];
    negative_keywords_add?: [KeywordTarget, ...KeywordTarget[]];
    negative_keywords_remove?: [KeywordTarget, ...KeywordTarget[]];
    optimization_goals?: [
        CanonicalOptimizationGoal,
        ...CanonicalOptimizationGoal[],
    ];
}[]

Operational patches keyed by package_id. Each package_id MUST appear at most once; sellers reject duplicate IDs atomically.

Type Declaration

package_id: string
Optionalbudget?: number | null

Replace this package's hard lifetime spend cap. A number in a resulting seller-optimized buy requires advertised media_buy.features.seller_optimized_package_budgets; otherwise rejected with UNSUPPORTED_FEATURE before any over-subscription validation.
Optionaldaily_budget_cap?: number | null

Replace this package's subordinate hard daily cap; null removes it. Numeric changes apply immediately with package spend already incurred in the shared current cap day counted.
Optionalmin_spend_target?: number | null

Replace this package's soft minimum-spend target. A number is valid only for seller-optimized allocation and requires advertised media_buy.features.seller_optimized_min_spend_targets; otherwise rejected with UNSUPPORTED_FEATURE before any over-subscription validation.
Optionalimpressions?: number
Optionalpacing?: Pacing
Optionalbidding?:
    | {
        automatic?: true;
        bid_amount?: number;
        max_bid?: number;
        cost_per?: { amount: number; strength: "cap"
        | "target" };
        roas?: { value: number; strength: "target" | "floor" };
    }
    | null
Optionalpaused?: boolean
Optionalcanceled?: true

Exercise an already-accepted unilateral package cancellation right. If seller agreement is required, refine the accepted proposal with change_kind amendment; cancellation proposals terminate the whole MediaBuy.
Optionalcancellation_reason?: string
Optionaltargeting_overlay?: TargetingOverlayInput
Optionalcatalog_ids?: [string, ...string[]]

Replace the package's promoted catalogs with references previously managed through sync_catalogs.

Min Items
1
Optionalkeyword_targets_add?: [KeywordTarget, ...KeywordTarget[]]

Min Items
1
Optionalkeyword_targets_remove?: [KeywordTarget, ...KeywordTarget[]]

Min Items
1
Optionalnegative_keywords_add?: [KeywordTarget, ...KeywordTarget[]]

Min Items
1
Optionalnegative_keywords_remove?: [KeywordTarget, ...KeywordTarget[]]

Min Items
1
Optionaloptimization_goals?: [CanonicalOptimizationGoal, ...CanonicalOptimizationGoal[]]

Min Items
1

`Optional`reporting_webhook

reporting_webhook?: ReportingWebhook

`Optional`governance_context

governance_context?: string

Min Length

Max Length

4096

`Optional`push_notification_config

push_notification_config?: PushNotificationConfig

`Optional`context

context?: ContextObject

`Optional`ext

ext?: ExtensionObject

Interface ControlMediaBuyRequest

Index

Properties

Properties

Optionaladcp_version

Optionaladcp_major_version

Deprecated

idempotency_key

Min Length

Max Length

Pattern

account

media_buy_id

Min Length

revision

Minimum

Format

Optionalname

Min Length

Max Length

Pattern

Optionalpaused

Optionalcanceled

Optionalcancellation_reason

Min Length

Max Length

Optionaltotal_budget

Type Declaration

amount: number

Minimum

currency: string

Pattern

Optionaldaily_budget_cap

Minimum

Optionalfrequency_cap

Type Declaration

Optionalsuppress?: Duration

Optionalsuppress_minutes?: number

Deprecated

Optionalmax_impressions?: number

Optionalper?: ReachUnit

Optionalwindow?: Duration

Optionalbudget_cap_timezone

Min Length

Optionalbudget_allocation

Optionalpacing

Optionalbidding

Type Declaration

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"

Optionalpackages

Type Declaration

package_id: string

Optionalbudget?: number | null

Optionaldaily_budget_cap?: number | null

Optionalmin_spend_target?: number | null

Optionalimpressions?: number

Optionalpacing?: Pacing

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

Optionalpaused?: boolean

Optionalcanceled?: true

Optionalcancellation_reason?: string

Optionaltargeting_overlay?: TargetingOverlayInput

Optionalcatalog_ids?: [string, ...string[]]

Min Items

Optionalkeyword_targets_add?: [KeywordTarget, ...KeywordTarget[]]

Min Items

Optionalkeyword_targets_remove?: [KeywordTarget, ...KeywordTarget[]]

Min Items

Optionalnegative_keywords_add?: [KeywordTarget, ...KeywordTarget[]]

Min Items

Optionalnegative_keywords_remove?: [KeywordTarget, ...KeywordTarget[]]

Min Items

`Optional`adcp_version

`Optional`adcp_major_version

`Optional`name

`Optional`paused

`Optional`canceled

`Optional`cancellation_reason

`Optional`total_budget

`Optional`daily_budget_cap

`Optional`frequency_cap

`Optional`suppress?: Duration

`Optional`suppress_minutes?: number

`Optional`max_impressions?: number

`Optional`per?: ReachUnit

`Optional`window?: Duration

`Optional`budget_cap_timezone

`Optional`budget_allocation

`Optional`pacing

`Optional`bidding

`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`packages

`Optional`budget?: number | null

`Optional`daily_budget_cap?: number | null

`Optional`min_spend_target?: number | null

`Optional`impressions?: number

`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" };
}
| null

`Optional`paused?: boolean

`Optional`canceled?: true

`Optional`cancellation_reason?: string

`Optional`targeting_overlay?: TargetingOverlayInput

`Optional`catalog_ids?: [string, ...string[]]

`Optional`keyword_targets_add?: [KeywordTarget, ...KeywordTarget[]]

`Optional`keyword_targets_remove?: [KeywordTarget, ...KeywordTarget[]]

`Optional`negative_keywords_add?: [KeywordTarget, ...KeywordTarget[]]

`Optional`negative_keywords_remove?: [KeywordTarget, ...KeywordTarget[]]

`Optional`optimization_goals?: [CanonicalOptimizationGoal, ...CanonicalOptimizationGoal[]]

`Optional`reporting_webhook

`Optional`governance_context

`Optional`push_notification_config

`Optional`context

`Optional`ext