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

    Interface LegacyPackageUpdate

    Package update configuration for update_media_buy. Identifies package by package_id and specifies fields to modify. Fields not present are left unchanged. Fully-immutable fields (product_id, format_ids, format_option_refs, format_kind, params, pricing_option_id) cannot appear in update payloads — schema-enforced via the not constraint at the root of this object. Pre-GA capability_ids is also rejected rather than accepted as an extension. The reporting contract field committed_metrics is append-only (sellers MUST accept new entries on update but reject attempts to modify or remove existing entries with validation_error per its own description).

    interface LegacyPackageUpdate {
        package_id: string;
        budget?: number | null;
        min_spend_target?: number | null;
        pacing?: Pacing;
        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" };
            }
            | null;
        impressions?: number;
        daily_budget_cap?: number
        | null;
        start_time?: string;
        end_time?: string;
        paused?: boolean;
        canceled?: true;
        cancellation_reason?: string;
        catalogs?: Catalog[];
        optimization_goals?: OptimizationGoal[];
        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 }[],
            ];
        };
        keyword_targets_add?: {
            keyword: string;
            match_type: MatchType;
            bid_price?: number;
        }[];
        keyword_targets_remove?: { keyword: string; match_type: MatchType }[];
        negative_keywords_add?: { keyword: string; match_type: MatchType }[];
        negative_keywords_remove?: { keyword: string; match_type: MatchType }[];
        creative_assignments?: {
            creative_id: string;
            weight?: number;
            rotation_mode?: "random" | "even" | "weighted" | "sequential";
            group_id?: string;
            sequence_position?: number;
            placement_refs?: [PlacementReference, ...PlacementReference[]];
            placement_ids?: [string, ...string[]];
        }[];
        creatives?: LegacyCompatibleCreativeAsset[];
        context?: ContextObject;
        ext?: ExtensionObject;
    }
    Index

    Properties

    package_id budget? min_spend_target? pacing? bid_price? bidding? impressions? daily_budget_cap? start_time? end_time? paused? canceled? cancellation_reason? catalogs? optimization_goals? targeting_overlay? keyword_targets_add? keyword_targets_remove? negative_keywords_add? negative_keywords_remove? creative_assignments? creatives? context? ext?

    Properties

    package_id: string

    Seller's ID of package to update

    budget?: number | null

    Updated hard 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 mode a number changes the package ceiling and null removes it so only the shared total and other constraints bound the package. null is invalid when the resulting allocation mode is fixed.

    0

    min_spend_target?: number | null

    Updated soft lifetime spend target for this package. A number is valid only for seller-optimized allocation and must not exceed the resulting package budget when one exists. null removes the target. Sellers MUST validate the complete post-update state atomically.

    0

    pacing?: Pacing
    bid_price?: number

    DEPRECATED in 3.2 and removed in the next major. Use bidding. A package update MUST NOT supply both a non-null bidding object and bid_price. During migration, bidding:null MAY accompany bid_price to clear the canonical block and set the legacy representation atomically.

    0

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

    Replace the complete package-authored bidding policy. An object replaces any prior package block and remains a complete override of the media-buy default. {automatic:true} explicitly selects provider automatic bidding at package scope. null clears the package-authored block so the package inherits media-buy bidding; if the media-buy block is also absent, provider automatic delivery applies. Monetary fields use the media-buy currency and require the package pricing option to declare that currency. During legacy migration, null MAY accompany bid_price or monetary optimization-goal targets; only a non-null canonical bidding object conflicts with those representations.

    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
    impressions?: number

    Updated impression goal for this package

    0

    daily_budget_cap?: number | null

    Replace this package's hard daily cap; null removes it. Numeric changes apply immediately with current-day package spend counted. A cap below that spend pauses the package for the day; the aggregate cap remains independently binding.

    0

    start_time?: string

    Updated flight start date/time for this package in ISO 8601 format. Must fall within the media buy's date range.

    date-time

    end_time?: string

    Updated flight end date/time for this package in ISO 8601 format. Must fall within the media buy's date range.

    date-time

    paused?: boolean

    Pause/resume specific package (true = paused, false = active)

    canceled?: true

    Cancel this specific package. Cancellation is irreversible — canceled packages stop delivery and cannot be reactivated. When true, package cancellation takes precedence over sibling fields on this package: the seller applies only canceled and cancellation_reason for this package and SHOULD return a structured warning naming ignored sibling fields. Root fields and other package updates still participate in the same atomic update when root canceled is absent. Sellers MAY reject with NOT_CANCELLABLE.

    cancellation_reason?: string

    Reason for canceling this package.

    500

    catalogs?: Catalog[]

    Replace the catalogs this package promotes. Uses replacement semantics — the provided array replaces the current list. Omit to leave catalogs unchanged.

    optimization_goals?: OptimizationGoal[]

    Replace all optimization goals for this package. Uses replacement semantics — omit to leave goals unchanged.

    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 }[],
        ];
    }

    Type Declaration

    • 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

    keyword_targets_add?: {
        keyword: string;
        match_type: MatchType;
        bid_price?: number;
    }[]

    Keyword targets to add or update on this package. Upserts by (keyword, match_type) identity: if the pair already exists, its bid_price is updated; if not, a new keyword target is added. Use targeting_overlay.keyword_targets in create_media_buy to set the initial list.

    Type Declaration

    • keyword: string

      The keyword to target

      1

    • match_type: MatchType
    • Optionalbid_price?: number

      Per-keyword bid price. Inherits currency and max_bid interpretation from the package's pricing option.

      0

    keyword_targets_remove?: { keyword: string; match_type: MatchType }[]

    Keyword targets to remove from this package. Removes matching (keyword, match_type) pairs. If a specified pair is not present, sellers SHOULD treat it as a no-op for that entry.

    Type Declaration

    • keyword: string

      The keyword to stop targeting

      1

    • match_type: MatchType
    negative_keywords_add?: { keyword: string; match_type: MatchType }[]

    Negative keywords to add to this package. Appends to the existing negative keyword list — does not replace it. If a keyword+match_type pair already exists, sellers SHOULD treat it as a no-op for that entry. Use targeting_overlay.negative_keywords in create_media_buy to set the initial list.

    Type Declaration

    • keyword: string

      The keyword to exclude

      1

    • match_type: MatchType
    negative_keywords_remove?: { keyword: string; match_type: MatchType }[]

    Negative keywords to remove from this package. Removes matching keyword+match_type pairs from the existing list. If a specified pair is not present, sellers SHOULD treat it as a no-op for that entry.

    Type Declaration

    • keyword: string

      The keyword to stop excluding

      1

    • match_type: MatchType
    creative_assignments?: {
        creative_id: string;
        weight?: number;
        rotation_mode?: "random" | "even" | "weighted" | "sequential";
        group_id?: string;
        sequence_position?: number;
        placement_refs?: [PlacementReference, ...PlacementReference[]];
        placement_ids?: [string, ...string[]];
    }[]

    Replace creative assignments for this package with optional rotation, grouping, weights, and placement routing. Uses replacement semantics - omit to leave assignments unchanged. rotation_mode is package-scoped: omission resolves to weighted, and every assignment MUST resolve to the same effective mode. In sequential mode, sequence_position MUST be unique within each package-local group. Sellers reject conflicts with VALIDATION_ERROR before mutation. When the same mutation narrows targeting_overlay.placement_selection, this complete replacement MUST remove or reroute every assignment reference that would otherwise be orphaned; the seller validates both changes atomically.

    Type Declaration

    • creative_id: string

      Unique identifier for the creative

    • Optionalweight?: number

      Relative delivery weight for this creative (0–100). Valid when the package's effective rotation_mode is weighted, including the backward-compatible default when rotation_mode is omitted. Weights determine impression distribution proportionally — a creative with weight 2 gets twice the delivery of weight 1. When omitted, the creative receives equal weight with other unweighted creatives. A weight of 0 means the creative is assigned but paused (receives no delivery).

    • Optionalrotation_mode?: "random" | "even" | "weighted" | "sequential"

      Package-scoped rotation policy repeated on assignment rows for wire compatibility. Omission means weighted, preserving existing weight behavior. Every assignment in a package MUST resolve to the same effective mode: weighted uses relative weights; even balances delivery across eligible assignments; sequential cycles through sequence_position in ascending order within each group; random makes an independent uniform selection from eligible assignments. Sellers MUST reject conflicting effective modes rather than choose one by array order.

    • Optionalgroup_id?: string

      Package-local creative pool identifier. The identifier has no meaning outside this package. Assignments that omit group_id belong to the package's default group; one eligible creative is selected from each applicable group per serving opportunity.

    • Optionalsequence_position?: number

      One-based order within the assignment's package-local group. Required only for sequential rotation and unique within that group.

    • Optionalplacement_refs?: [PlacementReference, ...PlacementReference[]]

      Optional structured refs routing this creative within already-purchased package inventory. This field never narrows purchased inventory; use targeting_overlay.placement_selection for that. Every ref MUST fall within the package's committed placement selection. When omitted, the creative runs across the purchased placements compatible with its format. New senders SHOULD include publisher_domain because placement IDs are publisher-scoped. If both placement_refs and legacy placement_ids are present, placement_refs wins.

      1

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

      Legacy shorthand routing IDs within already-purchased inventory. This field never narrows purchased inventory; use targeting_overlay.placement_selection. New senders SHOULD use placement_refs because IDs are publisher-scoped. If placement_refs is also present, receivers MUST ignore this field.

      1

    creatives?: LegacyCompatibleCreativeAsset[]

    Replace this package's inline creative assets. Native localization is not accepted on this path; use sync_creatives before assigning the library creative. When the seller also advertises creative.has_creative_library: true, new inline creatives enter the seller's creative library and can be reused by creative_id while retained; inline-only sellers may store them as package-scoped assets. Use creative_assignments instead for existing library creatives.

    context?: ContextObject
    ext?: ExtensionObject

    Settings

    Member Visibility

    On This Page

    Properties