Interface CancelMediaBuyInput

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.

  Min Items

  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

  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

  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.

  Min Items

  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?: TargetingOverlay

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

  Min Items

  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. Standard entries are symmetric with by_package[].metric_values; vendor entries reconcile to by_package[].vendor_metric_values; both use by_package[].missing_metrics for gaps. The atomic key remains (scope, metric_id, qualifier), with vendor identity included for vendor scope. Replaces the parallel-array design that shipped briefly in #3510.

  Min Items

  1

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

  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?: [PackageFormatSnapshot, ...PackageFormatSnapshot[]]

  Immutable canonical creative contracts established for this package. Each entry is a PackageFormatSnapshot of the selected effective Product format declaration. A package whose selected format carries tracker_execution_contract MUST retain and return this checklist even after creative coverage is complete; the live Product is never substituted for the package snapshot.

  Min Items

  1

• Optionalformats_pending?: PackageFormatSnapshot[]

  PackageFormatSnapshot entries from formats_to_provide that do not yet have creative coverage through sync_creatives or inline assignment. Every entry MUST equal its formats_to_provide snapshot after RFC 8785 canonicalization and, when product_snapshot_digest is present, carry the identical digest. An empty emitted array means every required format is covered. Absence means readiness was not reported.

• Optionalformat_ids_to_provide?: LegacyFormatReferenceStructuredObject[]

  Deprecated

  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

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

  Min Items

  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