Function updateMediaBuyResponse

Parameters

• data: {
      media_buy_id: string;
      media_buy_status?: MediaBuyStatus;
      status?: MediaBuyStatus;
      revision?: number;
      currency?: string;
      total_budget?: number;
      implementation_date?: string | null;
      invoice_recipient?: Omit<
          {
              legal_name: string;
              vat_id?: string;
              tax_id?: string;
              registration_number?: string;
              address?: {
                  street: string;
                  city: string;
                  postal_code: string;
                  region?: string;
                  country: string;
              };
              contacts?: {
                  role: "billing"
                  | "legal"
                  | "creative"
                  | "general";
                  name?: string;
                  email?: string;
                  phone?: string;
              }[];
              bank?: {
                  account_holder: string;
                  iban?: string;
                  bic?: string;
                  routing_number?: string;
                  account_number?: string;
              };
              ext?: Omit<Omit<{}, "bank">, "authentication"> & {
                  authentication?: unknown;
              };
          },
          "bank",
      >;
      affected_packages?: {
          package_id: string;
          product_id?: string;
          budget?: number;
          pacing?: Pacing;
          pricing_option_id?: string;
          bid_price?: number;
          price_breakdown?: {
              list_price: number;
              adjustments: (
                  Omit<Omit<{ [key: ...]: ... }, "bank">, "authentication"> & {
                      authentication?: unknown;
                  }
              )[];
          };
          impressions?: number;
          catalogs?: {
              catalog_id?: string;
              name?: string;
              type: CatalogType;
              url?: string;
              feed_format?: FeedFormat;
              update_frequency?: UpdateFrequency;
              items?: (Omit<(...), (...)> & { authentication?: ... })[];
              ids?: string[];
              gtins?: string[];
              tags?: string[];
              category?: string;
              query?: string;
              conversion_events?: EventType[];
              content_id_type?: ContentIDType;
              feed_field_mappings?: {
                  feed_field?: (...) | (...);
                  catalog_field?: (...) | (...);
                  asset_group_id?: (...) | (...);
                  value?: unknown;
                  transform?: (...) | (...) | (...) | (...) | (...);
                  format?: (...) | (...);
                  timezone?: (...) | (...);
                  by?: (...) | (...);
                  separator?: (...) | (...);
                  default?: unknown;
                  ext?: (...) | (...);
              }[];
          }[];
          format_ids?: {
              agent_url: string;
              id: string;
              width?: number;
              height?: number;
              duration_ms?: number;
          }[];
          format_option_refs?: (
              | {
                  scope: "publisher";
                  publisher_domain: string;
                  format_option_id: string;
              }
              | {
                  scope: "product";
                  format_option_id: string;
                  publisher_domain?: undefined;
              }
          )[];
          format_kind?: CanonicalFormatKind;
          params?: Omit<Omit<{}, "bank">, "authentication"> & {
              authentication?: unknown;
          };
          targeting_overlay?: {
              geo_countries?: string[];
              geo_countries_exclude?: string[];
              geo_regions?: string[];
              geo_regions_exclude?: string[];
              geo_metros?: { system: MetroAreaSystem; values: string[] }[];
              geo_metros_exclude?: { system: MetroAreaSystem; values: string[] }[];
              geo_postal_areas?: (
                  | { country: string; system: PostalCodeSystem; values: (...)[] }
                  | { system: LegacyPostalCodeSystem; values: (...)[] }
              )[];
              geo_postal_areas_exclude?: (
                  | { country: string; system: PostalCodeSystem; values: (...)[] }
                  | { system: LegacyPostalCodeSystem; values: (...)[] }
              )[];
              daypart_targets?: {
                  days: DayOfWeek[];
                  start_hour: number;
                  end_hour: number;
                  label?: string;
              }[];
              axe_include_segment?: string;
              axe_exclude_segment?: string;
              audience_include?: string[];
              audience_exclude?: string[];
              signal_targeting_groups?: {
                  operator: "all";
                  groups: { operator: (...)
                  | (...); signals: (...)[] }[];
              };
              signal_targeting?: (
                  | {
                      signal_ref?: (...)
                      | (...)
                      | (...)
                      | (...);
                      signal_id?: (...) | (...) | (...);
                      value_type: "binary";
                      value: boolean;
                  }
                  | {
                      signal_ref?: (...)
                      | (...)
                      | (...)
                      | (...);
                      signal_id?: (...) | (...) | (...);
                      value_type: "categorical";
                      values: (...)[];
                  }
                  | {
                      signal_ref?: (...)
                      | (...)
                      | (...)
                      | (...);
                      signal_id?: (...) | (...) | (...);
                      value_type: "numeric";
                      min_value?: (...) | (...);
                      max_value?: (...) | (...);
                  }
              )[];
              frequency_cap?: {
                  suppress?: {
                      interval: number;
                      unit: (...)
                      | (...)
                      | (...)
                      | (...)
                      | (...);
                  };
                  suppress_minutes?: number;
                  max_impressions?: number;
                  per?: ReachUnit;
                  window?: {
                      interval: number;
                      unit: (...)
                      | (...)
                      | (...)
                      | (...)
                      | (...);
                  };
              };
              property_list?: {
                  agent_url: string;
                  list_id: string;
                  auth_token?: string;
              };
              collection_list?: {
                  agent_url: string;
                  list_id: string;
                  auth_token?: string;
              };
              collection_list_exclude?: {
                  agent_url: string;
                  list_id: string;
                  auth_token?: string;
              };
              age_restriction?: {
                  min: number;
                  verification_required?: boolean;
                  accepted_methods?: AgeVerificationMethod[];
              };
              device_platform?: DevicePlatform[];
              device_type?: DeviceType[];
              device_type_exclude?: DeviceType[];
              store_catchments?: {
                  catalog_id: string;
                  store_ids?: (...)[];
                  catchment_ids?: (...)[];
              }[];
              geo_proximity?: (
                  | {
                      lat: number;
                      lng: number;
                      label?: (...)
                      | (...);
                      travel_time: { value: ...; unit: ... };
                      transport_mode: TransportMode;
                      ext?: (...) | (...);
                  }
                  | {
                      lat: number;
                      lng: number;
                      label?: (...)
                      | (...);
                      transport_mode?: (...) | (...);
                      radius: { value: ...; unit: ... };
                      ext?: (...) | (...);
                  }
                  | {
                      lat?: (...)
                      | (...);
                      lng?: (...) | (...);
                      label?: (...) | (...);
                      transport_mode?: (...) | (...);
                      geometry: { type: ...; coordinates: ... };
                      ext?: (...) | (...);
                  }
              )[];
              language?: string[];
              keyword_targets?: {
                  keyword: string;
                  match_type: MatchType;
                  bid_price?: number;
              }[];
              negative_keywords?: { keyword: string; match_type: MatchType }[];
          };
          measurement_terms?: {
              billing_measurement?: {
                  vendor: {
                      domain: string;
                      brand_id?: string;
                      industries?: (...)[];
                      data_subject_contestation?: { url?: ...; email?: ...; languages?: ... };
                      brand_kit_override?: {
                          logo?: ...;
                          colors?: ...;
                          voice?: ...;
                          tagline?: ...;
                      };
                  };
                  max_variance_percent?: number;
                  measurement_window?: string;
                  finalization_deadline_hours?: number;
              };
              makegood_policy?: { available_remedies: MakegoodRemedy[] };
          };
          performance_standards?: {
              metric: PerformanceStandardMetric;
              threshold: number;
              standard?: ViewabilityStandard;
              vendor: {
                  domain: string;
                  brand_id?: string;
                  industries?: string[];
                  data_subject_contestation?: {
                      url?: (...)
                      | (...);
                      email?: (...) | (...);
                      languages?: (...) | (...);
                  };
                  brand_kit_override?: {
                      logo?: (...)
                      | (...);
                      colors?: (...) | (...);
                      voice?: (...) | (...);
                      tagline?: (...) | (...);
                  };
              };
          }[];
          committed_metrics?: (
              | {
                  scope: "standard";
                  metric_id: AvailableMetric;
                  qualifier?: {
                      viewability_standard?: (...)
                      | (...);
                      completion_source?: (...) | (...);
                      attribution_methodology?: (...) | (...);
                      attribution_window?: (...) | (...);
                      lift_dimension?: (...) | (...);
                  };
                  committed_at: string;
              }
              | {
                  scope: "vendor";
                  vendor: {
                      domain: string;
                      brand_id?: string;
                      industries?: (...)[];
                      data_subject_contestation?: { url?: ...; email?: ...; languages?: ... };
                      brand_kit_override?: {
                          logo?: ...;
                          colors?: ...;
                          voice?: ...;
                          tagline?: ...;
                      };
                  };
                  metric_id: string;
                  committed_at: string;
              }
          )[];
          creative_assignments?: {
              creative_id: string;
              weight?: number;
              placement_refs?: {
                  publisher_domain?: (...)
                  | (...);
                  placement_id: string;
              }[];
              placement_ids?: string[];
          }[];
          format_ids_to_provide?: {
              agent_url: string;
              id: string;
              width?: number;
              height?: number;
              duration_ms?: number;
          }[];
          optimization_goals?: (
              | {
                  kind: "metric";
                  metric: | "attention_score"
                  | "clicks"
                  | "views"
                  | "completed_views"
                  | "reach"
                  | "engagements"
                  | "follows"
                  | "saves"
                  | "profile_visits"
                  | "viewed_seconds"
                  | "attention_seconds";
                  reach_unit?: ReachUnit;
                  target_frequency?: {
                      min?: (...)
                      | (...);
                      max?: (...) | (...);
                      window: { interval: ...; unit: ... };
                  };
                  view_duration_seconds?: number;
                  target?: | { kind: "cost_per"; value: number }
                  | { kind: "threshold_rate"; value: number };
                  priority?: number;
              }
              | {
                  kind: "event";
                  event_sources: {
                      event_source_id: string;
                      event_type: EventType;
                      custom_event_name?: (...)
                      | (...);
                      value_field?: (...) | (...);
                      value_factor?: (...) | (...);
                  }[];
                  target?: | { kind: "cost_per"; value: number }
                  | { kind: "per_ad_spend"; value: number }
                  | { kind: "maximize_value" };
                  attribution_window?: {
                      post_click?: (...) | (...);
                      post_view?: (...) | (...);
                      model?: (...) | (...);
                  };
                  priority?: number;
              }
              | {
                  kind: "vendor_metric";
                  vendor: {
                      domain: string;
                      brand_id?: string;
                      industries?: (...)[];
                      data_subject_contestation?: { url?: ...; email?: ...; languages?: ... };
                      brand_kit_override?: {
                          logo?: ...;
                          colors?: ...;
                          voice?: ...;
                          tagline?: ...;
                      };
                  };
                  metric_id: string;
                  target?: | { kind: "cost_per"; value: number }
                  | { kind: "threshold_rate"; value: number };
                  priority?: number;
              }
          )[];
          start_time?: string;
          end_time?: string;
          paused?: boolean;
          canceled?: boolean;
          cancellation?: {
              canceled_at: string;
              canceled_by: CanceledBy;
              reason?: string;
              acknowledged_at?: string;
          };
          agency_estimate_number?: string;
          creative_deadline?: string;
          context?: Omit<Omit<{}, "bank">, "authentication"> & {
              authentication?: unknown;
          };
          ext?: Omit<Omit<{}, "bank">, "authentication"> & {
              authentication?: unknown;
          };
      }[];
      valid_actions?: MediaBuyValidAction[];
      available_actions?: {
          action: MediaBuyValidAction;
          mode: MediaBuyActionMode;
          sla?: { response_max?: string; completion_max?: string };
          terms_ref?: string;
      }[];
      sandbox?: boolean;
      context?: Omit<Omit<{}, "bank">, "authentication"> & {
          authentication?: unknown;
      };
      ext?: Omit<Omit<{}, "bank">, "authentication"> & {
          authentication?: unknown;
      };
  }

  • media_buy_id: string

    Seller's identifier for the media buy

  • Optionalmedia_buy_status?: MediaBuyStatus

  • Optionalstatus?: MediaBuyStatus

  • Optionalrevision?: number

    Revision number after this update. Use this value in subsequent update_media_buy requests intended to change state for optimistic concurrency. Exact idempotency replays return the prior revision and do not increment revision.

    Minimum

    1

  • Optionalcurrency?: string

    ISO 4217 currency code for monetary values at this media buy level. Echoed when the update affects budget or currency. Matches the currency field in subsequent get_media_buys responses.

    Pattern

    ^[A-Z]{3}$

  • Optionaltotal_budget?: number

    Updated total budget amount across all packages, denominated in currency. Echoed when the update affects package budgets so buyers can verify the new aggregate without a round-trip to get_media_buys. Matches the total_budget field in subsequent get_media_buys responses.

    Minimum

    0

  • Optionalimplementation_date?: string | null

    ISO 8601 timestamp when changes take effect (null if pending approval)

    Format

    date-time

  • Optionalinvoice_recipient?: Omit<
        {
            legal_name: string;
            vat_id?: string;
            tax_id?: string;
            registration_number?: string;
            address?: {
                street: string;
                city: string;
                postal_code: string;
                region?: string;
                country: string;
            };
            contacts?: {
                role: "billing"
                | "legal"
                | "creative"
                | "general";
                name?: string;
                email?: string;
                phone?: string;
            }[];
            bank?: {
                account_holder: string;
                iban?: string;
                bic?: string;
                routing_number?: string;
                account_number?: string;
            };
            ext?: Omit<Omit<{}, "bank">, "authentication"> & {
                authentication?: unknown;
            };
        },
        "bank",
    >

  • Optionalaffected_packages?: {
        package_id: string;
        product_id?: string;
        budget?: number;
        pacing?: Pacing;
        pricing_option_id?: string;
        bid_price?: number;
        price_breakdown?: {
            list_price: number;
            adjustments: (
                Omit<Omit<{ [key: ...]: ... }, "bank">, "authentication"> & {
                    authentication?: unknown;
                }
            )[];
        };
        impressions?: number;
        catalogs?: {
            catalog_id?: string;
            name?: string;
            type: CatalogType;
            url?: string;
            feed_format?: FeedFormat;
            update_frequency?: UpdateFrequency;
            items?: (Omit<(...), (...)> & { authentication?: ... })[];
            ids?: string[];
            gtins?: string[];
            tags?: string[];
            category?: string;
            query?: string;
            conversion_events?: EventType[];
            content_id_type?: ContentIDType;
            feed_field_mappings?: {
                feed_field?: (...) | (...);
                catalog_field?: (...) | (...);
                asset_group_id?: (...) | (...);
                value?: unknown;
                transform?: (...) | (...) | (...) | (...) | (...);
                format?: (...) | (...);
                timezone?: (...) | (...);
                by?: (...) | (...);
                separator?: (...) | (...);
                default?: unknown;
                ext?: (...) | (...);
            }[];
        }[];
        format_ids?: {
            agent_url: string;
            id: string;
            width?: number;
            height?: number;
            duration_ms?: number;
        }[];
        format_option_refs?: (
            | {
                scope: "publisher";
                publisher_domain: string;
                format_option_id: string;
            }
            | {
                scope: "product";
                format_option_id: string;
                publisher_domain?: undefined;
            }
        )[];
        format_kind?: CanonicalFormatKind;
        params?: Omit<Omit<{}, "bank">, "authentication"> & {
            authentication?: unknown;
        };
        targeting_overlay?: {
            geo_countries?: string[];
            geo_countries_exclude?: string[];
            geo_regions?: string[];
            geo_regions_exclude?: string[];
            geo_metros?: { system: MetroAreaSystem; values: string[] }[];
            geo_metros_exclude?: { system: MetroAreaSystem; values: string[] }[];
            geo_postal_areas?: (
                | { country: string; system: PostalCodeSystem; values: (...)[] }
                | { system: LegacyPostalCodeSystem; values: (...)[] }
            )[];
            geo_postal_areas_exclude?: (
                | { country: string; system: PostalCodeSystem; values: (...)[] }
                | { system: LegacyPostalCodeSystem; values: (...)[] }
            )[];
            daypart_targets?: {
                days: DayOfWeek[];
                start_hour: number;
                end_hour: number;
                label?: string;
            }[];
            axe_include_segment?: string;
            axe_exclude_segment?: string;
            audience_include?: string[];
            audience_exclude?: string[];
            signal_targeting_groups?: {
                operator: "all";
                groups: { operator: (...)
                | (...); signals: (...)[] }[];
            };
            signal_targeting?: (
                | {
                    signal_ref?: (...)
                    | (...)
                    | (...)
                    | (...);
                    signal_id?: (...) | (...) | (...);
                    value_type: "binary";
                    value: boolean;
                }
                | {
                    signal_ref?: (...)
                    | (...)
                    | (...)
                    | (...);
                    signal_id?: (...) | (...) | (...);
                    value_type: "categorical";
                    values: (...)[];
                }
                | {
                    signal_ref?: (...)
                    | (...)
                    | (...)
                    | (...);
                    signal_id?: (...) | (...) | (...);
                    value_type: "numeric";
                    min_value?: (...) | (...);
                    max_value?: (...) | (...);
                }
            )[];
            frequency_cap?: {
                suppress?: {
                    interval: number;
                    unit: (...)
                    | (...)
                    | (...)
                    | (...)
                    | (...);
                };
                suppress_minutes?: number;
                max_impressions?: number;
                per?: ReachUnit;
                window?: {
                    interval: number;
                    unit: (...)
                    | (...)
                    | (...)
                    | (...)
                    | (...);
                };
            };
            property_list?: {
                agent_url: string;
                list_id: string;
                auth_token?: string;
            };
            collection_list?: {
                agent_url: string;
                list_id: string;
                auth_token?: string;
            };
            collection_list_exclude?: {
                agent_url: string;
                list_id: string;
                auth_token?: string;
            };
            age_restriction?: {
                min: number;
                verification_required?: boolean;
                accepted_methods?: AgeVerificationMethod[];
            };
            device_platform?: DevicePlatform[];
            device_type?: DeviceType[];
            device_type_exclude?: DeviceType[];
            store_catchments?: {
                catalog_id: string;
                store_ids?: (...)[];
                catchment_ids?: (...)[];
            }[];
            geo_proximity?: (
                | {
                    lat: number;
                    lng: number;
                    label?: (...)
                    | (...);
                    travel_time: { value: ...; unit: ... };
                    transport_mode: TransportMode;
                    ext?: (...) | (...);
                }
                | {
                    lat: number;
                    lng: number;
                    label?: (...)
                    | (...);
                    transport_mode?: (...) | (...);
                    radius: { value: ...; unit: ... };
                    ext?: (...) | (...);
                }
                | {
                    lat?: (...)
                    | (...);
                    lng?: (...) | (...);
                    label?: (...) | (...);
                    transport_mode?: (...) | (...);
                    geometry: { type: ...; coordinates: ... };
                    ext?: (...) | (...);
                }
            )[];
            language?: string[];
            keyword_targets?: {
                keyword: string;
                match_type: MatchType;
                bid_price?: number;
            }[];
            negative_keywords?: { keyword: string; match_type: MatchType }[];
        };
        measurement_terms?: {
            billing_measurement?: {
                vendor: {
                    domain: string;
                    brand_id?: string;
                    industries?: (...)[];
                    data_subject_contestation?: { url?: ...; email?: ...; languages?: ... };
                    brand_kit_override?: {
                        logo?: ...;
                        colors?: ...;
                        voice?: ...;
                        tagline?: ...;
                    };
                };
                max_variance_percent?: number;
                measurement_window?: string;
                finalization_deadline_hours?: number;
            };
            makegood_policy?: { available_remedies: MakegoodRemedy[] };
        };
        performance_standards?: {
            metric: PerformanceStandardMetric;
            threshold: number;
            standard?: ViewabilityStandard;
            vendor: {
                domain: string;
                brand_id?: string;
                industries?: string[];
                data_subject_contestation?: {
                    url?: (...)
                    | (...);
                    email?: (...) | (...);
                    languages?: (...) | (...);
                };
                brand_kit_override?: {
                    logo?: (...)
                    | (...);
                    colors?: (...) | (...);
                    voice?: (...) | (...);
                    tagline?: (...) | (...);
                };
            };
        }[];
        committed_metrics?: (
            | {
                scope: "standard";
                metric_id: AvailableMetric;
                qualifier?: {
                    viewability_standard?: (...)
                    | (...);
                    completion_source?: (...) | (...);
                    attribution_methodology?: (...) | (...);
                    attribution_window?: (...) | (...);
                    lift_dimension?: (...) | (...);
                };
                committed_at: string;
            }
            | {
                scope: "vendor";
                vendor: {
                    domain: string;
                    brand_id?: string;
                    industries?: (...)[];
                    data_subject_contestation?: { url?: ...; email?: ...; languages?: ... };
                    brand_kit_override?: {
                        logo?: ...;
                        colors?: ...;
                        voice?: ...;
                        tagline?: ...;
                    };
                };
                metric_id: string;
                committed_at: string;
            }
        )[];
        creative_assignments?: {
            creative_id: string;
            weight?: number;
            placement_refs?: {
                publisher_domain?: (...)
                | (...);
                placement_id: string;
            }[];
            placement_ids?: string[];
        }[];
        format_ids_to_provide?: {
            agent_url: string;
            id: string;
            width?: number;
            height?: number;
            duration_ms?: number;
        }[];
        optimization_goals?: (
            | {
                kind: "metric";
                metric: | "attention_score"
                | "clicks"
                | "views"
                | "completed_views"
                | "reach"
                | "engagements"
                | "follows"
                | "saves"
                | "profile_visits"
                | "viewed_seconds"
                | "attention_seconds";
                reach_unit?: ReachUnit;
                target_frequency?: {
                    min?: (...)
                    | (...);
                    max?: (...) | (...);
                    window: { interval: ...; unit: ... };
                };
                view_duration_seconds?: number;
                target?: | { kind: "cost_per"; value: number }
                | { kind: "threshold_rate"; value: number };
                priority?: number;
            }
            | {
                kind: "event";
                event_sources: {
                    event_source_id: string;
                    event_type: EventType;
                    custom_event_name?: (...)
                    | (...);
                    value_field?: (...) | (...);
                    value_factor?: (...) | (...);
                }[];
                target?: | { kind: "cost_per"; value: number }
                | { kind: "per_ad_spend"; value: number }
                | { kind: "maximize_value" };
                attribution_window?: {
                    post_click?: (...) | (...);
                    post_view?: (...) | (...);
                    model?: (...) | (...);
                };
                priority?: number;
            }
            | {
                kind: "vendor_metric";
                vendor: {
                    domain: string;
                    brand_id?: string;
                    industries?: (...)[];
                    data_subject_contestation?: { url?: ...; email?: ...; languages?: ... };
                    brand_kit_override?: {
                        logo?: ...;
                        colors?: ...;
                        voice?: ...;
                        tagline?: ...;
                    };
                };
                metric_id: string;
                target?: | { kind: "cost_per"; value: number }
                | { kind: "threshold_rate"; value: number };
                priority?: number;
            }
        )[];
        start_time?: string;
        end_time?: string;
        paused?: boolean;
        canceled?: boolean;
        cancellation?: {
            canceled_at: string;
            canceled_by: CanceledBy;
            reason?: string;
            acknowledged_at?: string;
        };
        agency_estimate_number?: string;
        creative_deadline?: string;
        context?: Omit<Omit<{}, "bank">, "authentication"> & {
            authentication?: unknown;
        };
        ext?: Omit<Omit<{}, "bank">, "authentication"> & {
            authentication?: unknown;
        };
    }[]

    For package-level updates, array of full Package objects showing complete post-update state for each directly modified package. This is a state snapshot, not a sparse delta: sellers MUST NOT return package_id-only stubs. Campaign-level updates that do not modify packages may return an empty array.

  • Optionalvalid_actions?: MediaBuyValidAction[]

    Flat-vocabulary actions the buyer can perform after this update. Saves a round-trip to get_media_buys. Deprecated in favor of available_actions[], which carries mode, optional SLA, and optional terms_ref. Sellers SHOULD populate both during the 3.x deprecation window; consumers MUST prefer available_actions[] when both are present. Removed in 4.0.

  • Optionalavailable_actions?: {
        action: MediaBuyValidAction;
        mode: MediaBuyActionMode;
        sla?: { response_max?: string; completion_max?: string };
        terms_ref?: string;
    }[]

    Structured per-buy resolution of actions available after this update. Authoritative — see get-media-buys-response.json for full semantics.

  • Optionalsandbox?: boolean

    When true, this response contains simulated data from sandbox mode.

  • Optionalcontext?: Omit<Omit<{}, "bank">, "authentication"> & { authentication?: unknown }

  • Optionalext?: Omit<Omit<{}, "bank">, "authentication"> & { authentication?: unknown }

• Optionalsummary: string