What changed on a media buy?

A storefront gives every media buy you book through it one revision number. It goes up by one each time the buy changes, whoever made the change. The history answers the next question: what changed at revision 7, and where did the change come from? Ask for it with include_history on get_media_buys, the AdCP read a storefront serves. Send a whole number from 1 to 1000. Each buy comes back with its latest entries, newest first. Leave it out, or send 0, and the buy carries no history.

{
  "media_buy_ids": ["sf_mb_1"],
  "include_history": 5
}

The V3 get tool (kind: "media_buy") does not return history today. Read it from the storefront’s get_media_buys.

What an entry says

{
  "media_buy_id": "sf_mb_1",
  "revision": 3,
  "history": [
    {
      "revision": 3,
      "timestamp": "2026-10-27T10:05:00.000Z",
      "action": "paused",
      "summary": "A connected platform reported the media buy as paused.",
      "ext": { "apostra": { "origin": "connected_platform" } }
    },
    {
      "revision": 2,
      "timestamp": "2026-10-27T10:02:00.000Z",
      "action": "updated_budget",
      "summary": "The buyer changed the budget.",
      "ext": { "apostra": { "origin": "adcp" } }
    }
  ]
}

Field	Meaning
`revision`	The revision of the buy after this change. Every new revision has exactly one entry.
`timestamp`	When the change was committed.
`action`	What happened: `created`, `updated`, `updated_budget`, `activated`, `paused`, `resumed`, `completed`, `canceled` or `rejected`. Treat an action you do not know as `updated`.
`summary`	A short sentence in plain words. It never names the media partner or ad server behind the buy.
`actor`	Who made the change, when the storefront knows. The storefront does not set it today, so do not rely on it.
`ext.apostra.origin`	Where the change came from, below.

Where a change came from

`origin`	Meaning
`adcp`	You or your agent: the buy was created, updated or canceled through a request you sent.
`connected_platform`	The media partner’s platform reported the change, for example that it paused or completed the buy.
`seller_system`	The storefront’s own handling, for example pausing a buy whose creation partly failed.
`seller_operator`	A person at the media partner made the change. The storefront does not use this value yet.
`unknown`	The storefront cannot say.

origin is an AdCP 3.3 field. Storefronts here speak AdCP 3.2, so it travels as ext.apostra.origin for now and moves onto the entry itself when Apostra moves to AdCP 3.3. Treat an origin you do not know as unknown.

What to rely on

Entries are never edited or removed. Cache an entry by its revision.
You may get fewer entries than revisions. include_history returns at most the number you ask for, applied to each buy. A buy that existed before history was kept has no entries for its earlier revisions, and its history starts at its next change. A missing entry for an old revision is not a missing change.
The history is the storefront’s own. It is numbered with the storefront’s revision, the one you cite. A media partner’s own history and revision numbers are not passed through.
Some storefronts do not return this history yet. A storefront whose inventory runs through a platform adapter answers get_media_buys itself, and its answer does not carry the history described here.
A failed read is an error, not an empty history. If the storefront cannot read the history it answers SERVICE_UNAVAILABLE with the reason media_buy_history_unavailable. Retry, or leave include_history out. See Errors for how to read an error.

Does your buy still match the booking?: whether a buy still matches what you booked.
Errors: how errors are reported.

Start building

Build your integration

Workflow recipes

MCP reference

Shared reference

What changed on a media buy?

What an entry says

Where a change came from

What to rely on

​What an entry says

​Where a change came from

​What to rely on

​Related

What an entry says

Where a change came from

What to rely on

Related