Update media buy

curl --request PATCH \
  --url https://api.interchange.io/api/v2/buyer/media-buys/{mediaBuyId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>"
}
'

import requests

url = "https://api.interchange.io/api/v2/buyer/media-buys/{mediaBuyId}"

payload = { "name": "<string>" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({name: '<string>'})
};

fetch('https://api.interchange.io/api/v2/buyer/media-buys/{mediaBuyId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "mediaBuy": {
    "mediaBuyId": "mb_ETBn4gJ9Wu",
    "name": "<string>",
    "status": "PENDING_APPROVAL",
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z",
    "pendingChange": {
      "status": "PENDING_APPROVAL",
      "differences": {
        "endTime": {
          "live": "<string>",
          "proposed": "<string>"
        },
        "budget": {
          "live": 123,
          "proposed": 123
        }
      },
      "reason": "Extended to 8/11 with W5+W6 gross budget"
    },
    "pendingSince": "2023-11-07T05:31:56Z",
    "sourceMessage": "<string>",
    "forwardedAt": "2023-11-07T05:31:56Z",
    "buyerReference": "sf:42:sf_mb_1783031864469_8pbc8mmr",
    "startTime": "<string>",
    "endTime": "<string>"
  },
  "warnings": [
    "<string>"
  ]
}

{
  "data": null,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "field": "<string>",
    "details": {}
  }
}

{
  "data": null,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "field": "<string>",
    "details": {}
  }
}

{
  "data": null,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "field": "<string>",
    "details": {}
  }
}

{
  "data": null,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "field": "<string>",
    "details": {}
  }
}

{
  "data": null,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "field": "<string>",
    "details": {}
  }
}

{
  "data": null,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "field": "<string>",
    "details": {}
  }
}

Campaigns

Update media buy

Partially update a single media buy, resolved top-level by mediaBuyId — the owning campaign is resolved server-side, consistent with GET /media-buys/. Rejected outright (not a warning) when it would violate a campaign invariant: currency (a product’s replacement pricing option settles in a different currency than this buy), budget headroom (the update would exceed the campaign’s remaining all-in budget), or mode compatibility (the campaign is directed and has no platform-managed update path). A flight date outside the campaign’s current window is not a failure — the campaign flight is widened to cover it and a warning is returned.

PATCH

media-buys

{mediaBuyId}

Update media buy

curl --request PATCH \
  --url https://api.interchange.io/api/v2/buyer/media-buys/{mediaBuyId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>"
}
'

import requests

url = "https://api.interchange.io/api/v2/buyer/media-buys/{mediaBuyId}"

payload = { "name": "<string>" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({name: '<string>'})
};

fetch('https://api.interchange.io/api/v2/buyer/media-buys/{mediaBuyId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "mediaBuy": {
    "mediaBuyId": "mb_ETBn4gJ9Wu",
    "name": "<string>",
    "status": "PENDING_APPROVAL",
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z",
    "pendingChange": {
      "status": "PENDING_APPROVAL",
      "differences": {
        "endTime": {
          "live": "<string>",
          "proposed": "<string>"
        },
        "budget": {
          "live": 123,
          "proposed": 123
        }
      },
      "reason": "Extended to 8/11 with W5+W6 gross budget"
    },
    "pendingSince": "2023-11-07T05:31:56Z",
    "sourceMessage": "<string>",
    "forwardedAt": "2023-11-07T05:31:56Z",
    "buyerReference": "sf:42:sf_mb_1783031864469_8pbc8mmr",
    "startTime": "<string>",
    "endTime": "<string>"
  },
  "warnings": [
    "<string>"
  ]
}

{
  "data": null,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "field": "<string>",
    "details": {}
  }
}

{
  "data": null,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "field": "<string>",
    "details": {}
  }
}

{
  "data": null,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "field": "<string>",
    "details": {}
  }
}

{
  "data": null,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "field": "<string>",
    "details": {}
  }
}

{
  "data": null,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "field": "<string>",
    "details": {}
  }
}

{
  "data": null,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "field": "<string>",
    "details": {}
  }
}

Authorizations

Authorization

string

header

required

API key or access token

Path Parameters

mediaBuyId

string

required

Buyer media buy ID

Minimum string length: 1

Example:

"mb_ETBn4gJ9Wu"

Body

application/json

Partial update for a single media buy, resolved top-level by mediaBuyId. Rejected outright (not warned) when it would violate a campaign invariant: currency (a product's replacement pricing option settles in a different currency), budget headroom (the update would exceed the campaign's remaining all-in budget), or mode compatibility (the campaign is directed — its mirrored media buy has no platform-managed update path).

name

string

Updated media buy name

Required string length: 1 - 255

packages

object[]

Per-package updates (for media buys with deployed packages)

Show child attributes

products

object[]

Product updates — additive (existing products not listed are preserved).

Show child attributes

start_time

string

"asap" or ISO 8601 date-time. A value earlier than the campaign's current flight start does not fail the request — it is applied and surfaced as a warning, and the campaign flight is widened to cover it.

end_time

string

ISO 8601 date-time. A value later than the campaign's current flight end does not fail the request — it is applied and surfaced as a warning, and the campaign flight is widened to cover it.

optimization_goals

object[]

Replace media-buy-level optimization goals; applied to every package at execution time. Pass an empty array to clear all goals.

Option 1
Option 2
Option 3

Show child attributes

creative_ids

string[]

Explicit creative IDs to attach to this media buy. Pass an empty array to clear all creatives.

Minimum string length: 1

updated_reason

string

Reason for the update (stored with the new version)

Maximum string length: 1000

Response

Update media buy

The updated media buy (why-visibility fields included) plus any non-blocking warnings.

mediaBuy

object

required

A single media buy with its why-visibility annotation (pendingReason, errorCode, forwardedAt, buyerReference). Use get_campaign for packages, products, and delivery.

Show child attributes

warnings

string[]

Non-blocking notices about this update, e.g. a flight date fell outside the campaign window (the campaign window was widened to cover it, rather than failing the request).

Get media buy List media buy packages

⌘I