@adcp/sdk API Reference - v14.0.0-beta.6
    Preparing search index...

    Interface LegacyUpdateMediaBuySuccess

    Success response - media buy updated successfully

    interface LegacyUpdateMediaBuySuccess {
        media_buy_id: string;
        name?: string;
        media_buy_status?: MediaBuyStatus;
        revision?: number;
        currency?: string;
        total_budget?: number;
        daily_budget_cap?: number;
        budget_cap_timezone?: 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" };
        };
        implementation_date?: string
        | null;
        invoice_recipient?: BusinessEntity;
        affected_packages?: {
            package_id: string;
            product_id?: string;
            audience_evidence_selections?: [
                AudienceEvidenceSelection,
                ...AudienceEvidenceSelection[],
            ];
            budget?: number;
            min_spend_target?: number;
            daily_budget_cap?: number;
            pacing?: Pacing;
            pricing_option_id?: string;
            bid_price?: number;
            bidding?: {
                automatic?: true;
                bid_amount?: number;
                max_bid?: number;
                cost_per?: { amount: number; strength: "cap"
                | "target" };
                roas?: { value: number; strength: "target" | "floor" };
            };
            price_breakdown?: PriceBreakdown;
            impressions?: number;
            catalogs?: Catalog[];
            format_ids?: LegacyFormatReferenceStructuredObject[];
            format_option_refs?: [FormatOptionReference, ...FormatOptionReference[]];
            format_kind?: CanonicalFormatKind;
            params?: {};
            targeting_overlay?: {
                geo_countries?: [string, ...string[]];
                geo_countries_exclude?: [string, ...string[]];
                geo_regions?: [string, ...string[]];
                geo_regions_exclude?: [string, ...string[]];
                geo_metros?: [
                    { system: MetroAreaSystem; values: [string, ...string[]] },
                    ...{ system: MetroAreaSystem; values: [string, ...string[]] }[],
                ];
                geo_metros_exclude?: [
                    { system: MetroAreaSystem; values: [string, ...string[]] },
                    ...{ system: MetroAreaSystem; values: [string, ...string[]] }[],
                ];
                geo_postal_areas?: [PostalArea, ...PostalArea[]];
                geo_postal_areas_exclude?: [PostalArea, ...PostalArea[]];
                geo_places?: [GeographicPlaceArea, ...GeographicPlaceArea[]];
                geo_places_exclude?: [GeographicPlaceArea, ...GeographicPlaceArea[]];
                daypart_targets?: [DaypartTarget, ...DaypartTarget[]];
                axe_include_segment?: string;
                axe_exclude_segment?: string;
                audience_include?: [string, ...string[]];
                audience_exclude?: [string, ...string[]];
                signal_targeting_groups?: PackageSignalTargetingGroups;
                signal_targeting?: [{}, ...{}[]];
                demographics?: DemographicTargetingIntent;
                frequency_cap?: {
                    suppress?: Duration;
                    suppress_minutes?: number;
                    max_impressions?: number;
                    per?: ReachUnit;
                    window?: Duration;
                };
                property_list?: PropertyListReference;
                property_list_exclude?: PropertyListReference;
                collection_list?: CollectionListReference;
                collection_list_exclude?: CollectionListReference;
                placement_selection?: PlacementSelection;
                age_restriction?: {
                    min: number;
                    verification_required?: boolean;
                    accepted_methods?: [AgeVerificationMethod, ...AgeVerificationMethod[]];
                };
                device_platform?: [DevicePlatform, ...DevicePlatform[]];
                device_platform_exclude?: [DevicePlatform, ...DevicePlatform[]];
                device_type?: [DeviceType, ...DeviceType[]];
                device_type_exclude?: [DeviceType, ...DeviceType[]];
                browser?: [BrowserFamily, ...BrowserFamily[]];
                browser_exclude?: [BrowserFamily, ...BrowserFamily[]];
                store_catchments?: [
                    {
                        catalog_id: string;
                        store_ids?: [string, ...string[]];
                        catchment_ids?: [string, ...string[]];
                    },
                    ...{
                        catalog_id: string;
                        store_ids?: [string, ...string[]];
                        catchment_ids?: [string, ...string[]];
                    }[],
                ];
                geo_proximity?: [{}, ...{}[]];
                language?: [string, ...string[]];
                keyword_targets?: [
                    { keyword: string; match_type: MatchType; bid_price?: number },
                    ...{ keyword: string; match_type: MatchType; bid_price?: number }[],
                ];
                negative_keywords?: [
                    { keyword: string; match_type: MatchType },
                    ...{ keyword: string; match_type: MatchType }[],
                ];
            };
            targeting_resolution?: PackageTargetingResolution;
            measurement_terms?: MeasurementTerms;
            performance_standards?: [PerformanceStandard, ...PerformanceStandard[]];
            committed_metrics?: [CommittedMetric, ...CommittedMetric[]];
            creative_assignments?: CreativeAssignment[];
            formats_to_provide?: [
                ProductFormatDeclaration,
                ...ProductFormatDeclaration[],
            ];
            formats_pending?: ProductFormatDeclaration[];
            format_ids_to_provide?: LegacyFormatReferenceStructuredObject[];
            format_ids_pending?: LegacyFormatReferenceStructuredObject[];
            optimization_goals?: [OptimizationGoal, ...OptimizationGoal[]];
            start_time?: string;
            end_time?: string;
            paused?: boolean;
            canceled?: boolean;
            cancellation?: {
                canceled_at: string;
                canceled_by: CanceledBy;
                reason?: string;
                acknowledged_at?: string;
            };
            agency_estimate_number?: string;
            creative_deadline?: string;
            context?: ContextObject;
            ext?: ExtensionObject;
        }[];
        valid_actions?: MediaBuyValidAction[];
        available_actions?: MediaBuyAvailableAction[];
        warnings?: {
            code: WarningCode;
            message: string;
            affected_resource: WarningAffectedResource;
            details?: {};
            ext?: ExtensionObject;
        }[];
        sandbox?: boolean;
        context?: ContextObject;
        ext?: ExtensionObject;
    }
    Index

    Properties

    media_buy_id name? media_buy_status? revision? currency? total_budget? daily_budget_cap? budget_cap_timezone? budget_allocation? pacing? bidding? implementation_date? invoice_recipient? affected_packages? valid_actions? available_actions? warnings? sandbox? context? ext?

    Properties

    media_buy_id: string

    Seller's identifier for the media buy

    name?: string

    Persisted human-readable name after the update. When update_media_buy supplied name, the seller MUST return the stored value here; a seller that could not apply the replacement SHOULD return the prior unchanged value rather than silently dropping the field. This display label is not an identifier or financial reference.

    1

    255

    \S

    media_buy_status?: MediaBuyStatus
    revision?: number

    Revision number after this update. Use this value in subsequent update_media_buy requests intended to change state for optimistic concurrency. Exact idempotency replays return the prior revision and do not increment revision.

    1

    currency?: string

    ISO 4217 currency code for monetary values at this media buy level. Echoed when the update affects budget or currency. Matches the currency field in subsequent get_media_buys responses.

    ^[A-Z]{3}$

    total_budget?: number

    Updated hard aggregate lifetime budget, denominated in currency. Echoed when the update affects the shared total or package budgets so buyers can verify the new aggregate without a round-trip to get_media_buys.

    0

    daily_budget_cap?: number

    Post-update hard aggregate daily spend ceiling. Echoed when the update sets or changes the aggregate daily cap; omitted after the cap is removed.

    0

    budget_cap_timezone?: string

    Post-update IANA timezone shared by every aggregate and package daily cap. Echoed whenever the update affects daily caps or their timezone.

    budget_allocation?: BudgetAllocation

    Post-update cross-package allocation configuration when affected by the update.

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

    Post-update media-buy-authored bidding policy when affected by the update, preserving explicit automatic mode, scope-specific goal binding, and media-buy-currency denomination. Omitted when the authored media-buy block was cleared.

    Type Declaration

    • 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.

    implementation_date?: string | null

    ISO 8601 timestamp when changes take effect (null if pending approval)

    date-time

    invoice_recipient?: BusinessEntity
    affected_packages?: {
        package_id: string;
        product_id?: string;
        audience_evidence_selections?: [
            AudienceEvidenceSelection,
            ...AudienceEvidenceSelection[],
        ];
        budget?: number;
        min_spend_target?: number;
        daily_budget_cap?: number;
        pacing?: Pacing;
        pricing_option_id?: string;
        bid_price?: number;
        bidding?: {
            automatic?: true;
            bid_amount?: number;
            max_bid?: number;
            cost_per?: { amount: number; strength: "cap"
            | "target" };
            roas?: { value: number; strength: "target" | "floor" };
        };
        price_breakdown?: PriceBreakdown;
        impressions?: number;
        catalogs?: Catalog[];
        format_ids?: LegacyFormatReferenceStructuredObject[];
        format_option_refs?: [FormatOptionReference, ...FormatOptionReference[]];
        format_kind?: CanonicalFormatKind;
        params?: {};
        targeting_overlay?: {
            geo_countries?: [string, ...string[]];
            geo_countries_exclude?: [string, ...string[]];
            geo_regions?: [string, ...string[]];
            geo_regions_exclude?: [string, ...string[]];
            geo_metros?: [
                { system: MetroAreaSystem; values: [string, ...string[]] },
                ...{ system: MetroAreaSystem; values: [string, ...string[]] }[],
            ];
            geo_metros_exclude?: [
                { system: MetroAreaSystem; values: [string, ...string[]] },
                ...{ system: MetroAreaSystem; values: [string, ...string[]] }[],
            ];
            geo_postal_areas?: [PostalArea, ...PostalArea[]];
            geo_postal_areas_exclude?: [PostalArea, ...PostalArea[]];
            geo_places?: [GeographicPlaceArea, ...GeographicPlaceArea[]];
            geo_places_exclude?: [GeographicPlaceArea, ...GeographicPlaceArea[]];
            daypart_targets?: [DaypartTarget, ...DaypartTarget[]];
            axe_include_segment?: string;
            axe_exclude_segment?: string;
            audience_include?: [string, ...string[]];
            audience_exclude?: [string, ...string[]];
            signal_targeting_groups?: PackageSignalTargetingGroups;
            signal_targeting?: [{}, ...{}[]];
            demographics?: DemographicTargetingIntent;
            frequency_cap?: {
                suppress?: Duration;
                suppress_minutes?: number;
                max_impressions?: number;
                per?: ReachUnit;
                window?: Duration;
            };
            property_list?: PropertyListReference;
            property_list_exclude?: PropertyListReference;
            collection_list?: CollectionListReference;
            collection_list_exclude?: CollectionListReference;
            placement_selection?: PlacementSelection;
            age_restriction?: {
                min: number;
                verification_required?: boolean;
                accepted_methods?: [AgeVerificationMethod, ...AgeVerificationMethod[]];
            };
            device_platform?: [DevicePlatform, ...DevicePlatform[]];
            device_platform_exclude?: [DevicePlatform, ...DevicePlatform[]];
            device_type?: [DeviceType, ...DeviceType[]];
            device_type_exclude?: [DeviceType, ...DeviceType[]];
            browser?: [BrowserFamily, ...BrowserFamily[]];
            browser_exclude?: [BrowserFamily, ...BrowserFamily[]];
            store_catchments?: [
                {
                    catalog_id: string;
                    store_ids?: [string, ...string[]];
                    catchment_ids?: [string, ...string[]];
                },
                ...{
                    catalog_id: string;
                    store_ids?: [string, ...string[]];
                    catchment_ids?: [string, ...string[]];
                }[],
            ];
            geo_proximity?: [{}, ...{}[]];
            language?: [string, ...string[]];
            keyword_targets?: [
                { keyword: string; match_type: MatchType; bid_price?: number },
                ...{ keyword: string; match_type: MatchType; bid_price?: number }[],
            ];
            negative_keywords?: [
                { keyword: string; match_type: MatchType },
                ...{ keyword: string; match_type: MatchType }[],
            ];
        };
        targeting_resolution?: PackageTargetingResolution;
        measurement_terms?: MeasurementTerms;
        performance_standards?: [PerformanceStandard, ...PerformanceStandard[]];
        committed_metrics?: [CommittedMetric, ...CommittedMetric[]];
        creative_assignments?: CreativeAssignment[];
        formats_to_provide?: [
            ProductFormatDeclaration,
            ...ProductFormatDeclaration[],
        ];
        formats_pending?: ProductFormatDeclaration[];
        format_ids_to_provide?: LegacyFormatReferenceStructuredObject[];
        format_ids_pending?: LegacyFormatReferenceStructuredObject[];
        optimization_goals?: [OptimizationGoal, ...OptimizationGoal[]];
        start_time?: string;
        end_time?: string;
        paused?: boolean;
        canceled?: boolean;
        cancellation?: {
            canceled_at: string;
            canceled_by: CanceledBy;
            reason?: string;
            acknowledged_at?: string;
        };
        agency_estimate_number?: string;
        creative_deadline?: string;
        context?: ContextObject;
        ext?: ExtensionObject;
    }[]

    Array of full Package objects showing complete post-update state for each modified package. This includes every active package whose budget was proportionally changed by a fixed-mode total_budget update. This is a state snapshot, not a sparse delta: sellers MUST NOT return package_id-only stubs. Campaign-level updates that do not modify packages may return an empty array.

    Type Declaration

    • package_id: string

      Seller's unique identifier for the package

    • Optionalproduct_id?: string

      ID of the product this package is based on. For packages created from an explicit create_media_buy package request, sellers MUST echo the request package's product_id on every response package object that represents that requested package.

    • Optionalaudience_evidence_selections?: [AudienceEvidenceSelection, ...AudienceEvidenceSelection[]]

      Exact immutable audience-evidence snapshots that affected recommendation, eligibility, or package construction. A confirmed package MUST include a package_construction selection matching every buyer audience_evidence_pin and every snapshot used to satisfy package audience_evidence_requirements; this readback remains mandatory on subsequent package read surfaces. This is decision provenance only; applied targeting remains exclusively in targeting_overlay and targeting_resolution.demographics.

      1

    • Optionalbudget?: number

      Hard lifetime spend cap for this package in the media-buy currency. Every selected pricing option in an AdCP-authored media buy MUST declare that same currency. In seller-optimized allocation mode this is a ceiling, not a current allocation. May be omitted when the package is bounded only by the shared media-buy total.

    • Optionalmin_spend_target?: number

      Soft lifetime spend target accepted for this package under seller-optimized budget allocation. This is an allocation preference, not a billing or delivery guarantee.

    • Optionaldaily_budget_cap?: number

      The hard package spend ceiling per shared media-buy cap day, in the media buy's currency. Sellers MUST echo this whenever a package daily cap is set. It is a subordinate ceiling, not a reserved or current allocation; the media buy's budget_cap_timezone defines its day boundary.

    • Optionalpacing?: Pacing
    • Optionalpricing_option_id?: string

      ID of the selected pricing option from the product's pricing_options array

    • Optionalbid_price?: number

      DEPRECATED legacy bidding representation. 3.2 sellers normalize accepted legacy input and SHOULD echo bidding instead. Removed in the next major.

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

      Package-authored bidding policy, echoed only when the buyer authored a package override. {automatic:true} is an explicit automatic-bidding override. Omission means the package inherits media-buy bidding or, when both scopes are absent, uses provider automatic delivery. Monetary fields are denominated in the media-buy currency. Sellers MUST NOT materialize inherited media-buy policy here.

      • 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.

    • Optionalprice_breakdown?: PriceBreakdown
    • Optionalimpressions?: number

      Impression goal for this package

    • Optionalcatalogs?: Catalog[]

      Catalogs this package promotes. Each catalog MUST have a distinct type (e.g., one product catalog, one store catalog). This constraint is enforced at the application level — sellers MUST reject requests containing multiple catalogs of the same type with a validation_error. Echoed from the create_media_buy request.

    • Optionalformat_ids?: LegacyFormatReferenceStructuredObject[]

      Deprecated in AdCP 3.2; removed in AdCP 4.0. Legacy named-format IDs supplied for this package on create_media_buy. Sellers SHOULD echo this field whenever the request included it, including dual-emission cases where format_option_refs was the winning selector, so read surfaces preserve the original wire contract. Omitted means the request did not carry legacy format_ids unless the seller cannot reconstruct legacy requests created before this field was persisted.

    • Optionalformat_option_refs?: [FormatOptionReference, ...FormatOptionReference[]]

      Structured 3.1+ format option references supplied for this package on create_media_buy. Sellers SHOULD echo this field whenever the request included it. Publisher-catalog-backed options are identified by { scope: "publisher", publisher_domain, format_option_id }; product-local options are identified by { scope: "product", format_option_id } and resolve only against this package's target product. Omitted means the request did not carry format_option_refs unless the seller cannot reconstruct legacy requests created before this field was persisted.

      1

    • Optionalformat_kind?: CanonicalFormatKind
    • Optionalparams?: {}

      Parameters for the direct canonical selector in format_kind, echoed from the create_media_buy request whenever the request included it. Requires format_kind; omitted only when the request did not carry direct canonical params or when the seller cannot reconstruct legacy requests created before this field was persisted.

    • Optionaltargeting_overlay?: {
          geo_countries?: [string, ...string[]];
          geo_countries_exclude?: [string, ...string[]];
          geo_regions?: [string, ...string[]];
          geo_regions_exclude?: [string, ...string[]];
          geo_metros?: [
              { system: MetroAreaSystem; values: [string, ...string[]] },
              ...{ system: MetroAreaSystem; values: [string, ...string[]] }[],
          ];
          geo_metros_exclude?: [
              { system: MetroAreaSystem; values: [string, ...string[]] },
              ...{ system: MetroAreaSystem; values: [string, ...string[]] }[],
          ];
          geo_postal_areas?: [PostalArea, ...PostalArea[]];
          geo_postal_areas_exclude?: [PostalArea, ...PostalArea[]];
          geo_places?: [GeographicPlaceArea, ...GeographicPlaceArea[]];
          geo_places_exclude?: [GeographicPlaceArea, ...GeographicPlaceArea[]];
          daypart_targets?: [DaypartTarget, ...DaypartTarget[]];
          axe_include_segment?: string;
          axe_exclude_segment?: string;
          audience_include?: [string, ...string[]];
          audience_exclude?: [string, ...string[]];
          signal_targeting_groups?: PackageSignalTargetingGroups;
          signal_targeting?: [{}, ...{}[]];
          demographics?: DemographicTargetingIntent;
          frequency_cap?: {
              suppress?: Duration;
              suppress_minutes?: number;
              max_impressions?: number;
              per?: ReachUnit;
              window?: Duration;
          };
          property_list?: PropertyListReference;
          property_list_exclude?: PropertyListReference;
          collection_list?: CollectionListReference;
          collection_list_exclude?: CollectionListReference;
          placement_selection?: PlacementSelection;
          age_restriction?: {
              min: number;
              verification_required?: boolean;
              accepted_methods?: [AgeVerificationMethod, ...AgeVerificationMethod[]];
          };
          device_platform?: [DevicePlatform, ...DevicePlatform[]];
          device_platform_exclude?: [DevicePlatform, ...DevicePlatform[]];
          device_type?: [DeviceType, ...DeviceType[]];
          device_type_exclude?: [DeviceType, ...DeviceType[]];
          browser?: [BrowserFamily, ...BrowserFamily[]];
          browser_exclude?: [BrowserFamily, ...BrowserFamily[]];
          store_catchments?: [
              {
                  catalog_id: string;
                  store_ids?: [string, ...string[]];
                  catchment_ids?: [string, ...string[]];
              },
              ...{
                  catalog_id: string;
                  store_ids?: [string, ...string[]];
                  catchment_ids?: [string, ...string[]];
              }[],
          ];
          geo_proximity?: [{}, ...{}[]];
          language?: [string, ...string[]];
          keyword_targets?: [
              { keyword: string; match_type: MatchType; bid_price?: number },
              ...{ keyword: string; match_type: MatchType; bid_price?: number }[],
          ];
          negative_keywords?: [
              { keyword: string; match_type: MatchType },
              ...{ keyword: string; match_type: MatchType }[],
          ];
      }
      • Optionalgeo_countries?: [string, ...string[]]

        Restrict delivery to specific countries. ISO 3166-1 alpha-2 codes (e.g., 'US', 'GB', 'DE').

        1

      • Optionalgeo_countries_exclude?: [string, ...string[]]

        Exclude specific countries from delivery. ISO 3166-1 alpha-2 codes (e.g., 'US', 'GB', 'DE').

        1

      • Optionalgeo_regions?: [string, ...string[]]

        Restrict delivery to exact canonical ISO 3166-2 subdivisions (states, provinces, regions, departments, or other subdivision categories). Unknown identifiers are invalid. At create or update, sellers MUST reject unsupported identifiers and MUST NOT silently widen, drop, or partially apply the list. During get_products, a seller may instead return a sparse, buyer-reviewable targeting_resolution modification for a valid but unsupported requested outcome. Exact internal translation preserves accepted identifiers in package readback.

        1

      • Optionalgeo_regions_exclude?: [string, ...string[]]

        Exclude exact canonical ISO 3166-2 subdivisions. Support is independent from geo_regions inclusion support. Unknown identifiers and values also present in geo_regions are invalid. At create or update, sellers MUST reject unsupported identifiers and partial application; during get_products, a seller may instead return a sparse, buyer-reviewable targeting_resolution modification for a valid but unsupported requested outcome.

        1

      • Optionalgeo_metros?: [
            { system: MetroAreaSystem; values: [string, ...string[]] },
            ...{ system: MetroAreaSystem; values: [string, ...string[]] }[],
        ]

        Restrict delivery to specific metro areas. Each entry specifies the classification system and target values. Seller must declare supported systems in get_adcp_capabilities.

        1

      • Optionalgeo_metros_exclude?: [
            { system: MetroAreaSystem; values: [string, ...string[]] },
            ...{ system: MetroAreaSystem; values: [string, ...string[]] }[],
        ]

        Exclude specific metro areas from delivery. Each entry specifies the classification system and excluded values. Seller must declare supported systems in get_adcp_capabilities.

        1

      • Optionalgeo_postal_areas?: [PostalArea, ...PostalArea[]]

        Restrict delivery to specific postal areas. Prefer the native country + postal system form. The deprecated legacy country-fused postal-system tokens remain accepted for compatibility. Seller must declare supported systems in get_adcp_capabilities.

        1

      • Optionalgeo_postal_areas_exclude?: [PostalArea, ...PostalArea[]]

        Exclude specific postal areas from delivery. Prefer the native country + postal system form. The deprecated legacy country-fused postal-system tokens remain accepted for compatibility. Seller must declare supported systems in get_adcp_capabilities.

        1

      • Optionalgeo_places?: [GeographicPlaceArea, ...GeographicPlaceArea[]]

        Restrict delivery to catalog-backed named places. Values MUST be stable identifiers in the declared system, not display names. Sellers must declare supported systems, countries, and place types in get_adcp_capabilities and reject unsupported entries rather than silently dropping them.

        1

      • Optionalgeo_places_exclude?: [GeographicPlaceArea, ...GeographicPlaceArea[]]

        Exclude catalog-backed named places. Uses the same identifier-based shape as geo_places. Sellers MUST reject overlap with geo_places for the same country, system, place_type, and value.

        1

      • Optionaldaypart_targets?: [DaypartTarget, ...DaypartTarget[]]

        Restrict delivery to specific time windows. Each entry specifies days of week and an hour range.

        1

      • Optionalaxe_include_segment?: string

        Deprecated: Use TMP provider fields instead. AXE segment ID to include for targeting.

      • Optionalaxe_exclude_segment?: string

        Deprecated: Use TMP provider fields instead. AXE segment ID to exclude from targeting.

      • Optionalaudience_include?: [string, ...string[]]

        Restrict delivery to members of these first-party CRM audiences. Only users present in the uploaded lists are eligible. References audience_id values from sync_audiences on the same seller account — audience IDs are not portable across sellers. Not for lookalike expansion — express that intent in the campaign brief. Seller must declare support in get_adcp_capabilities.

        1

      • Optionalaudience_exclude?: [string, ...string[]]

        Suppress delivery to members of these first-party CRM audiences. Matched users are excluded regardless of other targeting. References audience_id values from sync_audiences on the same seller account — audience IDs are not portable across sellers. Seller must declare support in get_adcp_capabilities.

        1

      • Optionalsignal_targeting_groups?: PackageSignalTargetingGroups
      • Optionalsignal_targeting?: [{}, ...{}[]]

        DEPRECATED. Use signal_targeting_groups for package-level signal targeting. Legacy flat signal_targeting remains accepted during the SignalRef migration window but cannot express grouped include/exclude composition or product-scoped pricing.

        1

      • Optionaldemographics?: DemographicTargetingIntent
      • 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 — 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.

      • Optionalproperty_list?: PropertyListReference
      • Optionalproperty_list_exclude?: PropertyListReference
      • Optionalcollection_list?: CollectionListReference
      • Optionalcollection_list_exclude?: CollectionListReference
      • Optionalplacement_selection?: PlacementSelection
      • Optionalage_restriction?: {
            min: number;
            verification_required?: boolean;
            accepted_methods?: [AgeVerificationMethod, ...AgeVerificationMethod[]];
        }

        Age restriction for compliance. Use for legal requirements (alcohol, gambling), not audience targeting.

        • min: number

          Minimum age required

        • Optionalverification_required?: boolean

          Whether verified age (not inferred) is required for compliance

        • Optionalaccepted_methods?: [AgeVerificationMethod, ...AgeVerificationMethod[]]

          Accepted verification methods. If omitted, any method the platform supports is acceptable.

          1

      • Optionaldevice_platform?: [DevicePlatform, ...DevicePlatform[]]

        Restrict to specific platforms. Use for technical compatibility (app only works on iOS). Values from Sec-CH-UA-Platform standard, extended for CTV.

        1

      • Optionaldevice_platform_exclude?: [DevicePlatform, ...DevicePlatform[]]

        Exclude specific operating-system platforms from delivery. When a platform appears in both device_platform and device_platform_exclude, exclusion wins. Sellers MUST reject a request they cannot enforce rather than silently dropping the exclusion.

        1

      • Optionaldevice_type?: [DeviceType, ...DeviceType[]]

        Restrict to specific device form factors. Use for campaigns targeting hardware categories rather than operating systems (e.g., mobile-only promotions, CTV campaigns).

        1

      • Optionaldevice_type_exclude?: [DeviceType, ...DeviceType[]]

        Exclude specific device form factors from delivery (e.g., exclude CTV for app-install campaigns).

        1

      • Optionalbrowser?: [BrowserFamily, ...BrowserFamily[]]

        Restrict delivery to specific canonical browser families in the impression delivery and rendering environment, not the post-click landing-page browser. Values MUST NOT be inferred solely from operating system, device, web/mobile-web inventory, or placement. Values in this array use OR semantics. When browser is supplied, families not listed are ineligible: other includes a seller-recognized family that is not explicitly enumerated, while unknown includes a browser the seller cannot classify into a recognized family. When the same family appears in browser and browser_exclude, exclusion wins. Browser and device constraints intersect; a seller that cannot enforce the exact combination MUST exclude or explicitly reconfigure the product during discovery and MUST reject it at create or update rather than silently widening delivery. Browser versions and seller-native IDs are intentionally unsupported.

        1

      • Optionalbrowser_exclude?: [BrowserFamily, ...BrowserFamily[]]

        Exclude specific canonical browser families from delivery. other excludes seller-recognized families that are not explicitly enumerated; unknown excludes browsers the seller cannot classify into a recognized family. When the same family appears in browser and browser_exclude, exclusion wins. Sellers MUST reject a request they cannot enforce rather than silently dropping the exclusion.

        1

      • Optionalstore_catchments?: [
            {
                catalog_id: string;
                store_ids?: [string, ...string[]];
                catchment_ids?: [string, ...string[]];
            },
            ...{
                catalog_id: string;
                store_ids?: [string, ...string[]];
                catchment_ids?: [string, ...string[]];
            }[],
        ]

        Target users within store catchment areas from a synced store catalog. Each entry references a store-type catalog and optionally narrows to specific stores or catchment zones.

        1

      • Optionalgeo_proximity?: [{}, ...{}[]]

        Target users within travel time, distance, or a custom boundary around arbitrary geographic points. Multiple entries use OR semantics — a user within range of any listed point is eligible. For campaigns targeting 10+ locations, consider using store_catchments with a location catalog instead. Seller must declare support in get_adcp_capabilities.

        1

      • Optionallanguage?: [string, ...string[]]

        Restrict to users with specific language preferences using canonical BCP 47 language ranges. Each buyer range is evaluated against a user's language-preference tag with RFC 4647 section 3.3.1 Basic Filtering: 'fr' matches 'fr', 'fr-CA', and 'fr-FR', while 'fr-CA' matches 'fr-CA' and more-specific descendants but not 'fr' or 'fr-FR'. Values use OR logic.

        1

      • Optionalkeyword_targets?: [
            { keyword: string; match_type: MatchType; bid_price?: number },
            ...{ keyword: string; match_type: MatchType; bid_price?: number }[],
        ]

        Keyword targeting for search and retail media platforms. Restricts delivery to queries matching the specified keywords. Each keyword is identified by the tuple (keyword, match_type) — the same keyword string with different match types are distinct targets. Sellers SHOULD reject duplicate (keyword, match_type) pairs within a single request. Seller must declare support in get_adcp_capabilities.

        1

      • Optionalnegative_keywords?: [
            { keyword: string; match_type: MatchType },
            ...{ keyword: string; match_type: MatchType }[],
        ]

        Keywords to exclude from delivery. Queries matching these keywords will not trigger the ad. Each negative keyword is identified by the tuple (keyword, match_type). Seller must declare support in get_adcp_capabilities.

        1

    • Optionaltargeting_resolution?: PackageTargetingResolution
    • Optionalmeasurement_terms?: MeasurementTerms
    • Optionalperformance_standards?: [PerformanceStandard, ...PerformanceStandard[]]

      Agreed performance standards for this package. When any entry specifies a vendor, creatives assigned to this package MUST include corresponding tracker_script or tracker_pixel assets from that vendor.

      1

    • Optionalcommitted_metrics?: [CommittedMetric, ...CommittedMetric[]]

      The binding reporting contract for this package — what the seller has agreed to populate in delivery reports. Each entry carries an explicit committed_at timestamp, so the array also serves as the contract amendment ledger: day-1 commitments share committed_at = create_media_buy.confirmed_at; mid-flight additions carry their own timestamps. When create_media_buy.confirmed_at is null for a provisional buy, sellers MUST omit committed_metrics until commitment. The first response that sets confirmed_at MAY include the initial committed-metrics set, and each such entry's committed_at MUST equal confirmed_at. The missing_metrics field on get_media_buy_delivery reconciles against this list, filtering to entries where committed_at < reporting_period.end (a metric committed mid-flight is only audited from its commitment timestamp forward). Sellers stamp the day-1 set on the create_media_buy response; mid-flight additions are appended via update_media_buy (append-only — sellers MUST reject attempts to modify or remove existing entries with validation_error, suggested code: IMMUTABLE_FIELD). Optional in v1; absence means the seller does not provide an audit-grade contract and missing_metrics falls back to the product's live available_metrics (a known audit gap — buyers SHOULD treat absence as 'no audit-grade contract' rather than 'clean delivery'). Each entry uses an explicit scope discriminator: standard for entries from the closed available-metric.json enum, vendor for vendor-defined metrics anchored on a BrandRef. The unified shape is symmetric with missing_metrics and aggregated_totals.metric_aggregates — same atomic unit (scope, metric_id, qualifier) across contract, diff, and delivery, so reconciliation collapses to a row-level join on the tuple. Replaces the parallel-array design that shipped briefly in #3510.

      1

    • Optionalcreative_assignments?: CreativeAssignment[]

      Creative assets assigned to this package, including the committed package-scoped rotation policy. Omitted rotation_mode reads as weighted for backward compatibility; all assignments resolve to one effective mode, and sequential positions are unique within each package-local group.

    • Optionalformats_to_provide?: [ProductFormatDeclaration, ...ProductFormatDeclaration[]]

      Canonical creative contracts that the buyer must satisfy for this package. Each entry is a package-time snapshot of a selected Product.format_options declaration (or the equivalent declaration normalized from a direct format_kind + params selector) and MUST equal or narrow that product contract. Full declarations keep the requirement stable if the live product or publisher catalog later changes and remain usable when format_option_id is absent. Sellers SHOULD emit this field whenever additional creative coverage is required.

      1

    • Optionalformats_pending?: ProductFormatDeclaration[]

      The declarations from formats_to_provide that do not yet have creative coverage through sync_creatives or inline creative assignment. An empty emitted array means every required format is covered. Absence means readiness was not reported, so buyers MUST NOT infer full coverage from omission. Sellers SHOULD emit this field with formats_to_provide when returning current package readiness.

    • Optionalformat_ids_to_provide?: LegacyFormatReferenceStructuredObject[]

      DEPRECATED in 3.2. Legacy named-format projection of formats_to_provide retained for older 3.x peers. New sellers emit canonical formats_to_provide declarations.

    • Optionalformat_ids_pending?: LegacyFormatReferenceStructuredObject[]

      DEPRECATED in 3.2. Legacy named-format projection of formats_pending retained for older 3.x peers. New sellers emit canonical formats_pending declarations. An empty emitted array means every projected requirement is covered. Absence means legacy readiness was not reported and MUST NOT be interpreted as full coverage.

    • Optionaloptimization_goals?: [OptimizationGoal, ...OptimizationGoal[]]

      Optimization targets for this package. The seller optimizes delivery toward these goals in priority order. Common pattern: event goals (purchase, install) as primary targets at priority 1; metric goals (clicks, views) as secondary proxy signals at priority 2+.

      1

    • Optionalstart_time?: string

      Flight start date/time for this package in ISO 8601 format. When omitted, the package inherits the media buy's start_time. Sellers SHOULD always include the resolved value in responses, even when inherited.

    • Optionalend_time?: string

      Flight end date/time for this package in ISO 8601 format. When omitted, the package inherits the media buy's end_time. Sellers SHOULD always include the resolved value in responses, even when inherited.

    • Optionalpaused?: boolean

      Whether this package is paused by the buyer. Paused packages do not deliver impressions. Defaults to false.

    • Optionalcanceled?: boolean

      Whether this package has been canceled. Canceled packages stop delivery and cannot be reactivated. Defaults to false.

    • Optionalcancellation?: {
          canceled_at: string;
          canceled_by: CanceledBy;
          reason?: string;
          acknowledged_at?: string;
      }

      Cancellation metadata. Present only when canceled is true.

      • canceled_at: string

        ISO 8601 timestamp when this package was canceled.

      • canceled_by: CanceledBy
      • Optionalreason?: string

        Reason the package was canceled.

      • Optionalacknowledged_at?: string

        ISO 8601 timestamp when the seller acknowledged the cancellation. Confirms inventory has been released and billing stopped. Absent until the seller processes the cancellation.

    • Optionalagency_estimate_number?: string

      Agency estimate or authorization number for this package. Echoed from the buyer's request. When present on the package, takes precedence over the media buy-level estimate number.

    • Optionalcreative_deadline?: string

      ISO 8601 timestamp for creative upload or change deadline for this package. After this deadline, creative changes are rejected. When absent, the media buy's creative_deadline applies.

    • Optionalcontext?: ContextObject
    • Optionalext?: ExtensionObject
    valid_actions?: MediaBuyValidAction[]

    Flat-vocabulary actions the buyer can perform after this update. Saves a round-trip to get_media_buys. Deprecated in favor of available_actions[], which carries mode, optional SLA, and optional terms_ref. Sellers SHOULD populate both during the 3.x deprecation window; consumers MUST prefer available_actions[] when both are present. Removed in 4.0.

    available_actions?: MediaBuyAvailableAction[]

    Structured per-buy resolution of actions available after this update. Authoritative — see get-media-buys-response.json for full semantics.

    warnings?: {
        code: WarningCode;
        message: string;
        affected_resource: WarningAffectedResource;
        details?: {};
        ext?: ExtensionObject;
    }[]

    Optional non-blocking observations accompanying this successful update. The requested update was still applied. Continuing conditions also appear on get_media_buys as current resource state.

    Type Declaration

    • code: WarningCode
    • message: string

      Short human-readable explanation. Treat as untrusted seller text and do not require buyers to parse it for routing.

    • affected_resource: WarningAffectedResource
    • Optionaldetails?: {}

      Optional seller-specific structured diagnostics. AdCP 3.2 defines interoperability through code and affected_resource only; buyers MUST NOT require portable keys inside details. Seller extensions that are not direct diagnostics belong in ext.

    • Optionalext?: ExtensionObject
    sandbox?: boolean

    When true, this response contains simulated data from sandbox mode.

    context?: ContextObject
    ext?: ExtensionObject

    Settings

    Member Visibility

    On This Page

    Properties