Interface BuyProductsRequest

Type Declaration

• amount: number

  Minimum

  0

• currency: string

  Pattern

  ^[A-Z]{3}$

Type Declaration

• 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

  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 across the owning field's full flight: the package flight for a targeting overlay, or the MediaBuy flight for a root cap.

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

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.

Type Declaration

• opportunity_id: string

  Opaque buyer-assigned identifier for this planning cycle, scoped to the seller and account.

• Optionalphase?: "exploratory" | "planning" | "active_sourcing"

  Current stage of buyer planning.

• Optionalintent?: "planning" | "test" | "speculative" | "live_rfp"

  How seriously the buyer is evaluating supply in this cycle.

• Optionalplanning_horizon?: DateRange

• Optionalresponse_deadline?: string

  Deadline by which the buyer needs a seller response.

• Optionalstatus?: "closed" | "open"

  Whether the planning cycle remains open. On calls after initial creation, omission means no status update and MUST NOT reopen or close the opportunity implicitly, except that successful create_media_buy proposal execution explicitly infers accepted closure.

• Optionalclose_reason?:
      | "other"
      | "budget_changed"
      | "selected_alternative"
      | "accepted_with_seller"
      | "purchased_elsewhere"
      | "not_pursued"
      | "timing_changed"

  Why the opportunity closed. Required when status is closed.

• Optionalclose_detail?: string

  Optional non-sensitive context about closure. MUST NOT identify a competitor or disclose confidential clearing terms.

• Optionalstatus?: "closed"