Interface Package

Seller's unique identifier for the package

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.

Budget allocation for this package in the currency specified by the pricing option

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

Bid price for auction-based pricing. This is the exact bid/price to honor unless the selected pricing option has max_bid=true, in which case bid_price is the buyer's maximum willingness to pay (ceiling).

Impression goal for this package

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.

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.

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.

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.

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.

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.

Creative assets assigned to this package

Format IDs that creative assets will be provided for this package

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

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.

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.

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

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

Cancellation metadata. Present only when canceled is true.

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.

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.