Interface GetMediaBuysResponse

Type Declaration

• media_buy_id: string

  Seller's unique identifier for the media buy

• Optionalaccount?: Account

• Optionalinvoice_recipient?: BusinessEntity

• status: MediaBuyStatus

• currency: string

  ISO 4217 currency code (e.g., USD, EUR, GBP) for monetary values at this media buy level. total_budget is always denominated in this currency. Package-level fields may override with package.currency.

• Optionaltotal_budget?: number

  Total budget amount across all packages, denominated in media_buy.currency

• Optionalstart_time?: string

  ISO 8601 flight start time for this media buy (earliest package start_time). Avoids requiring buyers to compute min(packages[].start_time).

• Optionalend_time?: string

  ISO 8601 flight end time for this media buy (latest package end_time). Avoids requiring buyers to compute max(packages[].end_time).

• Optionalcreative_deadline?: string

  ISO 8601 timestamp for creative upload deadline

• Optionalconfirmed_at?: string

  ISO 8601 timestamp when the seller confirmed this media buy. A successful create_media_buy response constitutes order confirmation.

• Optionalcancellation?: { canceled_at: string; canceled_by: CanceledBy; reason?: string }

  Cancellation metadata. Present only when status is 'canceled'.

  • canceled_at: string

    ISO 8601 timestamp when this media buy was canceled.

  • canceled_by: CanceledBy

  • Optionalreason?: string

    Reason the media buy was canceled.

• Optionalrevision?: number

  Current revision number. Pass this in update_media_buy for optimistic concurrency.

• Optionalcreated_at?: string

  Creation timestamp

• Optionalupdated_at?: string

  Last update timestamp

• Optionalvalid_actions?: (
      | "pause"
      | "resume"
      | "sync_creatives"
      | "cancel"
      | "update_budget"
      | "update_dates"
      | "update_packages"
      | "add_packages"
  )[]

  Actions the buyer can perform on this media buy in its current state. Eliminates the need for agents to internalize the state machine — the seller declares what is permitted right now.

• Optionalhistory?: {
      revision: number;
      timestamp: string;
      actor?: string;
      action: string;
      summary?: string;
      package_id?: string;
      ext?: ExtensionObject;
  }[]

  Revision history entries, most recent first. Only present when include_history > 0 in the request. Each entry represents a state change or update to the media buy. Entries are append-only: sellers MUST NOT modify or delete previously emitted history entries. Callers MAY cache entries by revision number. Returns min(N, available entries) when include_history exceeds the total.

• packages: PackageStatus[]

  Packages within this media buy, augmented with creative approval status and optional delivery snapshots

• Optionalext?: ExtensionObject