Opaque configured product ID returned by get_products. Selecting it accepts the product's disclosed targeting_resolution, pricing, forecast assumptions, and terms. Sellers MUST echo this value on every response package object that represents this requested package.
Optionalformat_ids?: [Deprecated in AdCP 3.2; removed in AdCP 4.0. Legacy named-format selector retained for older 3.x peers. New buyers MUST NOT emit this field. Sellers MUST normalize every entry through the canonical mapping path before product satisfaction checks; an entry that cannot be normalized is rejected with UNSUPPORTED_FEATURE before any equivalence check. When this field coexists with format_option_refs or format_kind plus params, sellers MUST compare the product option sets selected by each resolved route. Legacy parameter compatibility follows the asymmetric v2-narrows-v1 relation defined by canonical formats, not raw object equality. Different format shapes, selected option sets, or incompatible dimensions are rejected with CONFLICTING_SELECTORS; sellers MUST NOT silently ignore the legacy projection. Equivalent dual emission remains valid during the 3.x compatibility window. If omitted and no canonical selector is present, all formats supported by the product are active.
Optionalformat_option_refs?: [FormatOptionReference, ...FormatOptionReference[]]Canonical 3.2 format-option selector. Each reference matches one target product format_options[] entry. Publisher-backed options match { scope: "publisher", publisher_domain, format_option_id }; product-local options match { scope: "product", format_option_id }. Sellers reject unresolved options with UNSUPPORTED_FEATURE and a field path to the failing entry before comparing co-present routes. New buyers MUST use this route by itself and MUST NOT dual-emit either a direct canonical selector or deprecated format_ids. Receivers handling older 3.x multi-route requests MUST resolve every present route, require each route to select the same product option set, and reject disagreement with CONFLICTING_SELECTORS before treating format_option_refs as authoritative.
Optionalformat_kind?: CanonicalFormatKindOptionalparams?: {}Parameters for the direct canonical selector in format_kind. Shape follows the selected canonical's parameter vocabulary: dimensions (width, height, sizes), duration (duration_ms_exact, duration_ms_range), codecs, asset-source and slot narrowing, or other canonical-specific constraints. Requires format_kind. For fixed-size image selectors, width and height MUST co-occur; a selector containing only one dimension is schema-invalid. New buyers omit params when selecting by format_option_refs or format_ids; older multi-route requests are accepted only when every route selects the same product option set.
Optionalbudget?: numberHard lifetime spend cap for this package in the media buy's currency. Required in fixed allocation mode. Optional in seller-optimized mode; when omitted, the package is bounded by the shared total_budget and any other package constraints. In seller-optimized mode this is a ceiling, not a reserved or current allocation.
Optionalmin_spend_target?: numberSoft lifetime spend target for this package in the media buy's currency. Only valid with seller-optimized budget allocation. The seller SHOULD attempt to deliver at least this amount before allocating incremental spend elsewhere, but inventory, policy, optimization targets, or other delivery constraints may prevent it. This is not a billing guarantee. Must not exceed the package budget when both are present; sellers MUST reject with INVALID_REQUEST when this constraint is violated.
Optionalpacing?: PacingID of the selected pricing option from the product's pricing_options array
Optionalbid_price?: numberOptionalbidding?: BiddingPolicyPackage-authored bidding policy. This complete block replaces, rather than field-merges with, any media-buy bidding policy for this package. {automatic:true} explicitly overrides a media-buy policy with provider automatic bidding; omission inherits the complete media-buy block. Monetary fields use the media-buy currency, while the selected pricing option supplies only the auction unit and MUST declare that same currency. Sellers MUST reject a new bidding block combined with legacy bid_price or legacy monetary optimization-goal targets on the same effective package with AMBIGUOUS_BIDDING_POLICY.
Optionalimpressions?: numberImpression goal for this package
Optionaldaily_budget_cap?: numberOptional hard package daily spend ceiling in the media-buy currency. It is subordinate, not a reserved allocation; package caps need not sum to the aggregate cap. Uses the media buy's cap timezone. Requires advertised package budget-capping scope; otherwise rejected with UNSUPPORTED_FEATURE.
Optionalstart_time?: stringFlight start date/time for this package in ISO 8601 format. When omitted, the package inherits the media buy's start_time. Must fall within the media buy's date range.
Optionalend_time?: stringFlight end date/time for this package in ISO 8601 format. When omitted, the package inherits the media buy's end_time. Must fall within the media buy's date range.
Optionalpaused?: booleanWhether this package should be created in a paused state. Paused packages do not deliver impressions. Defaults to false.
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. Makes the package catalog-driven: one budget envelope, platform optimizes across items.
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+.
Optionaltargeting_overlay?: TargetingOverlayOptionalaudience_evidence_requirements?: AudienceEvidenceRequirementsOptionalaudience_evidence_pins?: [AudienceEvidencePin, ...AudienceEvidencePin[]]Exact immutable evidence snapshots selected by the buyer during discovery. The seller MUST match evidence_id, snapshot_id, version, and content_digest against one published snapshot and MUST reject catalog mutation, snapshot reuse, missing snapshots, or substitutions. Every accepted pin MUST be echoed in the confirmed package's audience_evidence_selections with decision_use package_construction.
Optionalmeasurement_terms?: MeasurementTermsOptionalperformance_standards?: [PerformanceStandard, ...PerformanceStandard[]]Buyer's proposed performance standards for this package. Overrides product defaults. Seller accepts, rejects with TERMS_REJECTED, or adjusts. When absent, product's performance_standards apply.
Optionalcommitted_metrics?: [Buyer's proposed reporting contract for this package — the metrics the buyer wants the seller to commit to populating in delivery reports. Same negotiation pattern as measurement_terms and performance_standards: seller accepts (echoes on confirmed package with committed_at stamped), rejects with TERMS_REJECTED (with explanation of which entries were unworkable), or normalizes (echoes a different but compatible list — buyer can accept by retrying with the normalized terms). When absent, the seller decides what to commit based on the product's available_metrics and the buyer's required_metrics filter on get_products. Each entry uses an explicit scope discriminator (standard or vendor) and identifies the metric — request-side entries do NOT carry committed_at; that timestamp is stamped by the seller on accept. Constraints on what the buyer MAY propose: each scope: standard entry's metric_id MUST be in the product's available_metrics, and each scope: vendor entry's (vendor, metric_id) MUST appear in the product's vendor_metrics — sellers SHOULD reject with TERMS_REJECTED and reference the offending entry when the proposal exceeds product capability.
Optionalcreative_assignments?: [CreativeAssignment, ...CreativeAssignment[]]Assign existing library creatives to this package with optional rotation, grouping, weights, and placement targeting. 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 creating the package.
Optionalcreatives?: [LegacyCompatibleCreativeAsset & {}, ...(LegacyCompatibleCreativeAsset & {})[]]Upload creative assets inline and assign to this package. 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, these 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.
Optionalagency_estimate_number?: stringAgency estimate or authorization number for this package. Overrides the media buy-level estimate number when different packages correspond to different agency estimates (e.g., different stations or flights within the same buy).
Optionalcontext?: ContextObjectOptionalext?: ExtensionObject
Package configuration for media buy creation.
Format selector contract (normative). New 3.2 buyers author at most one canonical selector route:
format_option_refs, orformat_kindwith optionalparams; omitting both selects all formats supported by the product. New buyers MUST NOT emit deprecatedformat_ids. During the 3.x compatibility window, receivers MUST continue to accept legacy-onlyformat_idsand older requests that carry more than one selector route.Receivers process selectors in this order: (1) independently resolve each present route to canonical declarations, without applying route precedence; an unresolved
format_option_refor a legacyformat_idthat cannot be normalized through the canonical mapping path MUST be rejected withUNSUPPORTED_FEATURE; (2) when every route resolves, derive the productformat_options[]entries selected by each route using directional product satisfaction, and require the selected option sets to match; legacy-to-canonical parameter compatibility uses the asymmetric v2 narrows v1 relation, not raw object equality; (3) reject different format shapes, selected option sets, or incompatible dimensions withCONFLICTING_SELECTORS; and only then (4) apply precedence:format_option_refs, thenformat_kindplusparams, thenformat_ids. Equivalent legacy dual emission remains valid. A single resolved route that does not satisfy the product is rejected withUNSUPPORTED_FEATURE.paramsrequiresformat_kind; for fixed-size image selectors,widthandheightMUST either both be present or both be absent.