> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apostra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Change a live media buy

> What you can change on a media buy that is already running, how to add a product to it, how to spend with another seller by adding a separate buy, and what a pending change, a revision and a CONFLICT mean.

Once a media buy has gone to the seller, the seller decides which changes it
takes. You can add a product or change a line item's targeting on the live buy
when the seller takes it, and you can add a separate media buy to the campaign
for anything it does not. This page says what you can change on the live buy,
how to read what the seller takes, how to add a product, change targeting or add
a separate buy, and what you will see while the seller decides.

> [!NOTE]
>
> This page describes what `save_media_buy` does today. Changes to how a live buy
> is edited will update it.

## What you can change on a live buy

`save_media_buy` with the buy's `mediaBuyId` can change a live buy in these
ways:

| You want to | Send | Result |
| - | - | - |
| Pause or resume it | `isPaused` | Pauses an active buy or resumes a paused one. Send it alone. |
| Stop it | `isCanceled: true` | Cancellation cannot be reversed. Send it alone. A draft cannot be canceled: archive it with `isArchived: true`. A guaranteed buy is canceled only after the seller approves: the call returns `cancellationPending: true` and the buy keeps its status until the seller approves and the seller's system completes the cancel, then it reads `canceled`. |
| End it earlier or later | `flight` with the current `startAt` and the new `endAt` | A running buy keeps its start. |
| Spend more or less on a product already on the buy | `products[].budget` (or `budget` on a one-line-item buy) | A line item's new total, including what it has spent. |
| Change the total of a shared-budget (`seller_optimized`) Meta buy | `budget` | The buy's new total, whatever number of products it has. The seller must take a budget change and may approve it first. It stays in the buy's currency and must fit the campaign's remaining budget. Meta refuses a total below what the buy has spent. |
| Change a bid | `products[].bidPrice` | Auction line items only. |
| Add a product | `products[]` with `productId`, `pricingOptionId` and `budget` | Only where `liveChanges.addProducts` is not `not_accepted`. Send it alone. See [Add a product to a live buy](https://docs.apostra.com/v3/change-a-live-media-buy.md#add-a-product-to-a-live-buy). |
| Change a line item's pacing | `products[].pacing` | `even`, `asap` or `front_loaded`. Only where `liveChanges.changePacing` is not `not_accepted`. See [Change pacing on a live buy](https://docs.apostra.com/v3/change-a-live-media-buy.md#change-pacing-on-a-live-buy). |
| Change a line item's frequency cap | `products[].targetingOverlay.frequency_cap` | Only where `liveChanges.changeFrequencyCap` is not `not_accepted`. Send it alone, and see [Change targeting on a live buy](https://docs.apostra.com/v3/change-a-live-media-buy.md#change-targeting-or-a-frequency-cap-on-a-live-buy). |
| Change a line item's targeting | `products[].targetingOverlay` | Only where `liveChanges.changeTargeting` is not `not_accepted`. Send it alone. See [Change targeting on a live buy](https://docs.apostra.com/v3/change-a-live-media-buy.md#change-targeting-or-a-frequency-cap-on-a-live-buy). |
| Add or remove a creative | `save_creative` with `campaignIds` | Not `save_media_buy`: a creative runs on a campaign and reaches each running buy of it. Only where `liveChanges.assignCreatives` or `removeCreatives` is not `not_accepted`. See [Add or remove a creative on a live buy](https://docs.apostra.com/v3/change-a-live-media-buy.md#add-or-remove-a-creative-on-a-live-buy). |
| Rename it | `name` | Only on some platforms, and only after the seller confirms. |

A change that goes through returns the media buy as `get` returns it right after
the write, in `mediaBuy`: the new budget, the new `updatedAt`, and any change still
waiting on the seller as `pendingChange`. You do not need to read the buy again to
see what you wrote.

On a buyer account with [spend approval](https://docs.apostra.com/v3/account-access.md#spend-approval-on-a-buyer-account)
on, a change that raises what the buy spends in total (a higher budget, a higher
sum of line item budgets, or an added product) returns `approval_required`
instead. Nothing is written or sent to the seller until an administrator
approves it on the Apostra site; repeat the call with the same `idempotencyKey`
to read the outcome. The approved change runs only while the buy still spends
what it did when you asked. Moving budget between the buy's own line items with
the total unchanged, lowering a budget, and every other change in the table go
through as usual.

The buyer workflow guide has the rules and examples for each one:
[Change a live media buy](https://docs.apostra.com/v2/setup/v3/buyer-workflows.md#change-a-live-media-buy),
[Pause, resume, or cancel one media buy](https://docs.apostra.com/v2/setup/v3/buyer-workflows.md#pause-resume-or-cancel-one-media-buy)
and
[Rename a live media buy](https://docs.apostra.com/v2/setup/v3/buyer-workflows.md#rename-a-live-media-buy).

## What the seller takes

`get` with `kind: "media_buy"` returns `liveChanges` on an active or paused buy
whose seller has declared what it accepts. It answers per kind of change:

| Field | Meaning |
| - | - |
| `addProducts` | Adding a product to this buy. It reads `not_accepted` when the buy has no single storefront to send the product through, even if the seller takes adds, so it matches what the write does. |
| `removeProducts` | Removing a product from this buy. |
| `changeBudget` | Changing the buy's budget, including the total of a shared-budget buy. |
| `changeTargeting` | Changing the targeting of a line item already on this buy. |
| `changeFrequencyCap` | Changing the frequency cap of a line item already on this buy. |
| `changePacing` | Changing the pacing of a line item already on this buy. |
| `assignCreatives` | Assigning a creative to this buy, by attaching it to the buy's campaign. |
| `removeCreatives` | Removing a creative from this buy, by detaching it from the buy's campaign. |

Each is one of:

* `accepted`: the seller applies the change.
* `conditional`: the seller applies the change when it meets conditions the seller
  sets on that action, so it can still refuse a particular change.
* `needs_seller_approval`: the seller reviews it first. The live buy keeps
  running until the seller accepts.
* `not_accepted`: the seller declared what it takes for this buy and this change
  is not among it.

The field is absent on a buy that is not live, and on a live buy whose seller
declared nothing. Absence does not mean the seller refuses, and it does not mean
the seller accepts. Read the field rather than guessing.

When a buy runs through a storefront, the storefront is the seller you ask, and
its answer comes from the sources the buy is routed to. Each source says which
actions it takes on its part of the buy, and the storefront re-reads that every
time it checks the source. A change that every source part must take (pausing,
resuming, changing the budget) is accepted only when every source part declares
it. Adding or removing a product is accepted when any source part declares it,
because the product you add goes to the one source that sells it. Where the
source parts differ in how they take a change, the storefront reports the one
that needs the most seller involvement. A source part that has declared nothing
takes nothing. A change to a storefront buy can lag a source's own change by up
to the time between those checks, a few minutes.

Other changes are refused, and nothing is applied:

* **Adding a product** returns `ACTION_NOT_ALLOWED` when the seller does not
  take it, the buy has no single storefront to send it through
  (`liveChanges.addProducts` is `not_accepted`), or the seller has declared
  nothing.
  `details.mutation_outcome` is `not_dispatched`, `details.reason` is
  `seller_does_not_accept` or `seller_declared_no_actions`, and
  `details.recovery` is `create_separate_media_buy`: stage a separate buy on the
  same campaign, as a later section shows.
* **Removing a product** (`remove: true`) from a live buy is a decision for the
  seller, like an add. `liveChanges.removeProducts` says whether the seller
  takes it, from the `remove_packages` action it declared. When it does, Apostra
  sends the removal to the seller as a package cancellation (`canceled: true` on
  the package) and returns the seller's answer. A removal stands alone: send
  nothing else in the same call. The packages change only when the seller
  confirms: a removal the seller accepts but has not applied reads as
  `pending_approval` and leaves the packages as they are, and a removal the
  seller refuses leaves the buy unchanged. A package cancellation cannot be
  undone. Removing the last live package is refused; cancel the buy instead.
  A removal names the line item and nothing else: `productId`, and
  `lineItemRef` when the product is on several line items, which must match the
  product when both are given. Package cancels of one buy run one at a time, and a
  package whose removal the seller accepted but has not applied counts as
  removed when the next removal is checked against the last live package. When
  Apostra next reads the buy from the seller, a package the seller reports
  canceled confirms the removal. A package the seller still shows live seven days
  after the removal was sent counts as live again, so you can send the removal
  again. Apostra's operations team follows up with the seller about the removal
  that was not applied. If an
  earlier package cancel of the same buy is still being sent after fifteen seconds,
  the call is refused as `SERVICE_UNAVAILABLE` with `mutation_outcome:
  "not_dispatched"`: nothing was sent, so retry it.
  When the seller does not take it, or has declared nothing, the call returns
  `ACTION_NOT_ALLOWED` with `details.mutation_outcome` `not_dispatched`,
  `details.action` `remove_packages` and `details.reason`
  `seller_does_not_accept` or `seller_declared_no_actions`, and nothing is sent.
  When the seller refuses after the send, `details.reason` is `seller_refused`
  and `details.seller_code` is its code, such as `NOT_CANCELLABLE`. Neither
  answer offers a separate buy, because the product is already on this buy. It
  is allowed on a draft as before.
* **Changing the budget** returns `ACTION_NOT_ALLOWED` with `details.action`
  `update_budget` when the seller does not take it (`liveChanges.changeBudget` is
  `not_accepted`) or has declared nothing. Nothing is sent and the buy is
  unchanged. To spend a different total, cancel the buy and create a new one on
  the same campaign. A product budget is the total for the flight, so on Snap a
  budget change is taken only when the buy's ad squads carry lifetime budgets,
  as every Snap buy Apostra places does. A Snap buy whose ad squads carry a
  daily budget, such as one placed before Apostra switched Snap buys to
  lifetime budgets in November 2026 or one whose budget was changed to a daily
  amount in Snap Ads Manager, does not take a budget change; change its budget
  in Snap Ads Manager. Such a buy reports its daily budget as a daily budget
  (`ext.scope3.daily_budget_target`), never as the buy's total. A Google buy is placed the same way: Apostra creates the
  Google campaign with a total budget over the buy's start and end dates, so
  Google stops spending when the buy's total is reached, not at that amount each
  day. Google accepts a total budget only on some campaign types, and Apostra
  refuses to place a Google buy on a type that does not take one. A TikTok buy
  is placed the same way: its campaign and ad groups hold a lifetime budget for
  the flight, so a TikTok buy needs an end date. A TikTok buy whose campaign or
  ad groups carry a daily budget, such as one made in TikTok Ads Manager, does
  not take a budget change; change its budget in TikTok Ads Manager.
* **Changing targeting** returns `ACTION_NOT_ALLOWED` when the seller does not
  take it (`liveChanges.changeTargeting` is `not_accepted`) or has declared
  nothing. `details.mutation_outcome` is `not_dispatched`, `details.action` is
  `update_targeting` and `details.reason` is `seller_does_not_accept` or
  `seller_declared_no_actions`. To get the targeting you want anyway, create a
  new buy with it.
* **Changing a frequency cap** returns `ACTION_NOT_ALLOWED` the same way, with
  `details.action` `update_frequency_caps`, when `liveChanges.changeFrequencyCap`
  is `not_accepted` or the seller has declared nothing. A seller that takes
  targeting changes does not thereby take frequency caps: they are separate
  actions.
* **Changing pacing** returns `ACTION_NOT_ALLOWED` when
  `liveChanges.changePacing` is `not_accepted` or the seller has declared
  nothing. It speaks AdCP's own refusal: `details.attempted_action` and
  `details.action` are `update_pacing`, `details.reason` is `not_supported_on_buy`
  and `details.mutation_outcome` is `not_dispatched`.
* **Assigning or removing a creative** is refused when the seller declared what
  it takes for this buy and left the change out (`liveChanges.assignCreatives` or
  `removeCreatives` is `not_accepted`). The refusal is
  [on `save_creative`](https://docs.apostra.com/v3/change-a-live-media-buy#add-or-remove-a-creative-on-a-live-buy).
* **Moving a line item to another source or seller route** returns
  `NOT_IMPLEMENTED` naming the field.

## Add a product to a live buy

When `liveChanges.addProducts` is `accepted`, `conditional` or
`needs_seller_approval`, send the product to the live buy:

```json theme={null}
{
  "name": "save_media_buy",
  "arguments": {
    "mediaBuyId": "MEDIA_BUY_ID",
    "products": [
      {
        "productId": "QUALIFIED_PRODUCT_ID",
        "pricingOptionId": "RETURNED_PRICING_OPTION_ID",
        "budget": 2000
      }
    ],
    "idempotencyKey": "NEW_KEY_FOR_THIS_CHANGE"
  }
}
```

What to know before you send it:

* **The product must come from a seller the buy already trades with.** The add
  goes through the storefront the buy's line items already use, and that storefront
  places it with its own source. A product from another seller, or from a source
  the buy has no line with, is refused and nothing changes: add a separate buy
  instead. A buy that trades with more than one seller does not take an add yet.
* **The product must have been offered to this buy's buyer.** A product the
  seller composed for one buyer (priced with that buyer's discount, built for
  one account, or shaped by a seller lesson for one buyer or brand) is added
  only to a buy booked by that buyer, and a product built for one account only
  to a buy booked under that account. For any other buy it is refused as a
  product the storefront does not sell.
* **Send it alone.** An add sent with `flight`, `budget`, `name` or a change to a
  product already on the buy returns `VALIDATION_ERROR` on `products` and nothing
  is sent. `pricingOptionId` and `budget` are required, and `bidPrice` is
  optional. `targetingOverlay` and `performanceStandards` are not supported on an
  added product and return `NOT_IMPLEMENTED` naming the field. An added product
  takes the campaign's own targeting, as a product on a new buy does. If the
  seller cannot apply a campaign targeting dimension to the new line item, the
  add is refused by name and nothing is sent.
* **The pricing option must settle in the buy's currency**, and the budget counts
  against the campaign's remaining budget. A product priced in another currency,
  or an add that takes the campaign over its budget, is refused.
* **The seller decides.** The call returns `action: "updated"` once the seller has
  applied the add. When the seller has taken it and not yet applied it, the call
  returns `action: "pending_approval"`: the live buy keeps running on what it had,
  the waiting add shows as `pendingChange`, and you should not send it again. A
  seller that refuses the add itself returns `ACTION_NOT_ALLOWED` with
  `details.reason` `seller_refused` and `details.recovery`
  `create_separate_media_buy`; the buy is left as it was.
* **A seller that has declared nothing is not asked.** Where `liveChanges` is
  absent the add is refused with `seller_declared_no_actions`, because AdCP has
  a seller advertise what it takes.

### Adding a product to a Meta buy

On a Meta buy the add creates a new ad set inside the buy's existing Meta
campaign. The campaign, its other ad sets and their spend are not touched, and
the new ad set takes the targeting, optimization and budget of the product you
add, exactly as when a Meta buy is first created. It runs for the rest of the
buy's flight, so a buy that is running switches the new ad set on and a paused
buy leaves it paused.

An add is refused, with nothing changed on Meta, when:

* the product runs a different campaign objective from the buy's campaign;
* the buy shares one campaign budget across its ad sets (`seller_optimized`);
  create a separate buy for the product instead;
* the Meta campaign was created outside Apostra, or has no end date; or
* the request also changes something else, or names a package `paused` flag or
  start and end dates of its own.

If Meta rejects the new ad set partway, Apostra removes only the ad sets that
add created and reports that it did. The buy keeps running on what it had.

### Adding a product to a Google buy

On a Google Search buy the add creates a new ad group inside the buy's existing
Google campaign. The campaign, its other ad groups and their serving state are
not touched: a running campaign keeps running and a paused one stays paused. The
campaign budget goes up by the budget of the product you add, so it stays the
sum of the buy's product budgets, and the new ad group takes the keyword
targeting of the product, exactly as when a Google buy is first created. A new
ad group has no ads until you sync a creative to it.

An add is refused, with nothing changed on Google, when:

* the buy is not a Search buy, or it is a Performance Max buy (its package is
  the campaign itself);
* the product uses a different bidding strategy from the buy's campaign, is not
  one Apostra can book on Google today, or asks for its own optimization goal;
* the product targets other countries or regions than the campaign, because
  Google targets geography on the whole campaign;
* the package asks for an audience, its own `paused` flag, a bid, start and end
  dates, or any other setting an added ad group cannot take;
* the buy was created outside Apostra, or its budget is no longer the sum of its
  product budgets in Google; or
* the request also changes something else, or names a stale `revision`.

If Google rejects the new ad group partway, Apostra removes only the ad groups
that add created, puts the budget back and reports that it did; the buy keeps
running on what it had. Google keeps a removed ad group visible as removed, so
it can still show up in Google Ads and as a canceled package on the buy. If
Apostra cannot confirm it undid everything, the error names what to check in
Google Ads. The campaign is never paused or removed by a failed add.

### Adding a product to a TikTok buy

On a TikTok buy the add creates a new ad group inside the buy's existing TikTok
campaign. The campaign and its other ad groups are not touched: a running
campaign keeps running and a paused one stays paused. The campaign budget goes up
by the budget of the product you add, so it stays the sum of the buy's product
budgets, and the new ad group takes the targeting of the product, exactly as when
a TikTok buy is first created. It runs for the rest of the buy's flight. It is
created paused and has no ad until you sync a creative to it, so adding a product
never starts delivery: resume the new package when its creative is in place.

Send the product with `productId`, `pricingOptionId` and `budget`, and at most a
`targetingOverlay` with countries, regions and a frequency cap. The budget must
reach TikTok's minimum for the days left in the flight.

An add is refused, with nothing changed on TikTok, when:

* the buy is not a standard TikTok campaign with a lifetime budget, whose ad
  groups all end on one date that has not passed and all optimize for one goal
  (a Smart+, Search, catalog or daily-budget buy does not take an add);
* the campaign budget is no longer the sum of its ad group budgets, or the buy
  was created before Apostra recorded its targeting;
* the product needs a pixel, an app, a lead form, a catalog or an identity, runs
  a different campaign objective from the buy, or optimizes for a different goal;
* the package asks for an audience, its own `paused` flag, a bid, start and end
  dates, a creative, or any other setting an added ad group cannot take; or
* the request also changes something else, or names a stale `revision`.

If TikTok rejects the new ad group partway, Apostra removes only the ad groups
that add created, puts the budget back and reports that it did; the buy keeps
running on what it had. If Apostra cannot confirm it undid everything, the error
says so and the ad groups to check in TikTok Ads Manager are reported to
Apostra's operators. The campaign is never paused or deleted by a failed add.

If TikTok does not confirm the campaign budget raise after a few repeats, Apostra
keeps the added ad groups and their targeting record, so a budget that lands late
is backed by them, and the error says so. Read the media buy again to see whether
its budget now includes them, and do not add the packages a second time.

### If you are the seller

A seller whose buy declares `add_packages` can now receive a live add request on
it. The storefront treats an add like any other material change to a live buy:
it applies the storefront's own approval rule, so when the storefront requires
approval for changes to live buys the add waits in the same approval queue and
the live buy keeps delivering until it is decided. The add reaches the seller's
source as `new_packages` on `update_media_buy`, and a source that refuses it is
reported to the buyer as `ACTION_NOT_ALLOWED` with the reason `seller_refused`.
A seller that does not want adds simply does not declare `add_packages` for the
buy, and the buyer is told so before anything is sent.

## Change targeting or a frequency cap on a live buy

When `liveChanges.changeTargeting` is `accepted`, `conditional` or
`needs_seller_approval`, send the new targeting on the line item:

```json theme={null}
{
  "name": "save_media_buy",
  "arguments": {
    "mediaBuyId": "MEDIA_BUY_ID",
    "products": [
      {
        "productId": "PRODUCT_ID_ALREADY_ON_THE_BUY",
        "lineItemRef": "LINE_ITEM_REF",
        "targetingOverlay": { "geo_countries": ["US"] }
      }
    ],
    "idempotencyKey": "NEW_KEY_FOR_THIS_CHANGE"
  }
}
```

What to know before you send it:

* **It reaches the seller as a package change.** On a live buy the seller reads
  the buy's packages, so the new targeting goes to every open package of the
  line item. A package whose flight has ended keeps the targeting it had. Like
  every change to a live buy, it is staged as a pending version beside the
  running one and applied when the seller confirms.
* **It follows the same rules as targeting on a draft.** The overlay is AdCP's
  `targeting_overlay`, a dimension you set to `null` is cleared, a dimension you
  leave out is left as it was, and the buy's campaign constraints still apply.
  A dimension the seller's capabilities do not list is refused before anything is
  sent.
* **Send it alone.** Targeting sent with `flight`, `budget`, `name` or any other
  change to a product returns `VALIDATION_ERROR` on `products` with
  `details.mutation_outcome` `not_dispatched`.
* **A frequency cap is its own change, decided by its own action.** A
  `targetingOverlay.frequency_cap` is sent the same way as targeting, on the
  line item, and goes to the same open packages. The seller decides it by
  `liveChanges.changeFrequencyCap` (its `update_frequency_caps` action), not by
  `changeTargeting`. An overlay that carries both a frequency cap and another
  targeting dimension needs both answers to be other than `not_accepted`, and is
  refused on the first that is. `null` clears the cap.
* **The seller decides.** The call returns `action: "updated"` once the seller
  has applied the change. When the seller has taken it and not yet applied it,
  the call returns `action: "pending_approval"`: the live buy keeps running on
  its current targeting, the waiting change shows as `pendingChange`, and you
  should not send it again. A seller that refuses the change itself returns
  `ACTION_NOT_ALLOWED` with `details.action` `update_targeting` and
  `details.reason` `seller_refused`; the buy is left as it was.
* **A seller that has declared nothing is not asked.** Where `liveChanges` is
  absent the change is refused with `seller_declared_no_actions`.

## Change pacing on a live buy

When `liveChanges.changePacing` is `accepted`, `conditional` or
`needs_seller_approval`, send the new pacing on the line item:

```json theme={null}
{
  "name": "save_media_buy",
  "arguments": {
    "mediaBuyId": "MEDIA_BUY_ID",
    "products": [
      {
        "productId": "PRODUCT_ID_ALREADY_ON_THE_BUY",
        "lineItemRef": "LINE_ITEM_REF",
        "pacing": "front_loaded"
      }
    ],
    "idempotencyKey": "NEW_KEY_FOR_THIS_CHANGE"
  }
}
```

* **The values are AdCP's own:** `even`, `asap` or `front_loaded`. Any other
  value is rejected before anything is sent.
* **It reaches the seller as a package change.** The new pacing goes to every
  open package of the line item, as `update_media_buy` `packages[].pacing`. A
  package whose flight has ended keeps its pacing. Like every change to a live
  buy it is staged as a pending version beside the running one and applied when
  the seller confirms, and the call waits for the seller's answer.
* **Package pacing sits under the media buy's pacing.** In AdCP, a package's
  pacing is subordinate to the pacing of the buy it belongs to: it cannot make
  the buy deliver faster than the buy's own pacing allows.
* **A seller-optimized buy does not take it yet.** AdCP lets a seller take
  package pacing inside such a buy only when it declares
  `seller_optimized_package_pacing`, which Apostra does not read yet. The call
  returns `NOT_IMPLEMENTED` naming `products[n].pacing`, and nothing is sent.
* **It can go with a targeting or frequency-cap change** on the same line, and
  each is decided by its own seller answer, but not with `flight`, `budget`,
  `name` or any other change to a product, which returns `VALIDATION_ERROR` on
  `products`.
* **The seller decides.** The result is `action: "updated"` once applied, or
  `action: "pending_approval"` while the seller has it and has not applied it
  (the buy keeps its current pacing and the change shows as `pendingChange`; do
  not send it again). A seller that refuses a change it took returns
  `ACTION_NOT_ALLOWED` with `details.reason` `seller_refused`.
* **On a draft** the pacing is saved on the line item, with no seller involved.
  A new buy takes its pacing from `budget.pacing`, and `products[].pacing` on a
  create returns `VALIDATION_ERROR`.

## Add or remove a creative on a live buy

A creative is not set on a media buy. It runs on a campaign, and attaching it
sends it to every running buy of that campaign whose products accept its format;
detaching it takes it off them. So you change which creatives a live buy runs
with `save_creative`, by changing the campaigns the creative runs on:

```json theme={null}
{
  "name": "save_creative",
  "arguments": {
    "creativeId": "CREATIVE_ID",
    "advertiserId": "ADVERTISER_ID",
    "campaignIds": ["CAMPAIGN_ID", "ANOTHER_CAMPAIGN_ID"],
    "idempotencyKey": "NEW_KEY_FOR_THIS_CHANGE"
  }
}
```

To swap one creative for another on a campaign, attach the new one and detach
the old one: two `save_creative` calls, each decided on its own.

Attachment permits the same format adaptations as delivery. For example, an
image without a slot binding can fit a product that declares an `image_main`
slot. A creative whose format cannot fit a campaign product is still refused.
Creative manifests with a legacy format reference or a pinned option retain
their existing attachment checks; the seller can still refuse them at delivery.

* **The seller decides, by what it declared.** An attach reaches a running buy as
  an assignment change, which the seller takes when it declares
  `update_creative_assignments`; a detach is a removal, which it takes when it
  declares `remove_creative`. `liveChanges.assignCreatives` and
  `liveChanges.removeCreatives` on each buy report the seller's answer, from the
  same code the write uses. `replace_creative` is not used: it changes a
  creative's own content on a package, which an attach or a detach does not do.
* **A refusal is whole and happens first.** If the seller of any running buy the
  change reaches declared actions and left the change out, `save_creative`
  returns `ACTION_NOT_ALLOWED` with AdCP's own reason, `details.reason:
  "not_supported_on_buy"`, `details.attempted_action` `update_creative_assignments`
  or `remove_creative`, `details.mediaBuyId` and `details.campaignId`, and
  `details.mutation_outcome: "not_dispatched"`. Nothing is attached, detached or
  sent to a seller, so the campaign and the creative are as they were. A buy
  whose products do not accept the creative's format is not asked, because the
  creative would not be sent to it.
* **A seller that declared nothing is not refused.** Creatives have always
  reached a running buy whose seller declared no actions, and this does not stop
  them. Only a seller that declared what it takes and left the change out rules
  it out, and that stays the case while sellers are asked to declare what they
  take. This differs from adding a product, targeting, a frequency cap and
  pacing, which a seller that declared nothing does not take.
* **The result says where the change went.** `save_creative` returns
  `liveMediaBuys` with the running buys an attach or detach was queued to. Each
  is a pending change on that buy: the buy keeps running as it was and the
  creative is applied when the seller confirms, which shows as `pendingChange` on
  `get` with `kind: "media_buy"`. Delivery to the seller is durable and retried,
  so the call returns before every seller has answered.
* **Revision, history and retry.** Each running buy takes the change through its
  normal update. Where the buy's storefront keeps its history, that is a new
  revision with an entry in [Media buy history](https://docs.apostra.com/v3/media-buy-history.md) whose
  `origin` is `adcp`; a storefront whose inventory runs through a platform
  adapter does not return that history yet. The
  membership write is `CONFLICT`-safe: another change to the same creative or
  campaign in flight returns `CONFLICT`, and a membership that changed while the
  request was prepared returns `CONFLICT` too. Read the creative and send the
  full set again. Repeating the same `campaignIds` changes nothing.
* **The campaign side follows the same rule.** `save_campaign` with
  `creativeIds` replaces the campaign's creatives, and each creative it attaches
  or detaches is checked against the sellers of the campaign's running buys by
  the same code. A refusal is `ACTION_NOT_ALLOWED` with the same AdCP details,
  on `creativeIds`, and no creative is attached or detached. Because
  `save_campaign` can also change other campaign fields in the same call, a
  refusal there can come after those changes were saved: the error says so with
  `partialWrite` and "prior changes were already saved". To be sure nothing else
  is saved, send `creativeIds` on its own.
* **Not covered yet.** V3 has no way yet to assign a creative to one buy or one
  package: a campaign's creatives go to every package they fit. Re-sending a
  changed creative (the resync) is not gated by this check.

### Adding a creative to a live Meta buy

A Meta buy takes an attached creative while it runs: `liveChanges.assignCreatives`
is accepted on every Meta buy with at least one ad set. Apostra sends the
creative to the Meta ad account and creates an ad for it in each of the buy's ad
sets whose product accepts its format. The campaign, its ad sets, their budgets
and the other ads are not touched.

* **The new ad follows the buy.** On a running buy the ad is created running; on
  a paused buy it is created paused, so adding a creative never starts delivery.
  Meta reviews the new ad as it does any other.
* **Formats.** `meta_image_feed`, `meta_video_feed`, `meta_stories`,
  `meta_reels` and `meta_existing_post` can be added. The ad set must place
  the format: a creative whose placements the ad set does not target, or a
  video longer than one of its placements allows, is refused.
* **Removing a creative is not taken.** Meta does not take a removal from a live
  buy (`liveChanges.removeCreatives` is `not_accepted`), so detaching a creative
  from a campaign with a running Meta buy is refused with `not_supported_on_buy`.
  Pause the ad in Meta Ads Manager, or cancel the buy and book a new one.
* **The ad account needs a Facebook Page.** As for any Meta creative, the ad
  account must have an authorized Facebook Page. Without one the creative is not
  sent, and the error names the ad account to fix.

## Spend more with another seller, or when the seller does not take an add

To add a product the seller does not take on the live buy, or one from a
different seller, to a campaign that is already running, create a separate media
buy on the same campaign. Do not create a new campaign: the
campaign, its budget and its other buys stay as they are.

1. Find the product. Use `search` with `kind: "wholesale_product"` or
   `request_proposals`. Keep every identity field it returns and its
   `productQueryId`.
2. Check the campaign has room. Staging a buy that takes the campaign over its
   remaining budget scales the new lines down and returns a warning that names
   the requested and staged amount. When no budget is left, the call is refused
   with a `VALIDATION_ERROR` that names the products it could not fund. To
   spend more in total, raise the campaign budget first with `save_campaign`.
3. Stage the buy: `save_media_buy` with the `campaignId`, the seller's
   `sellerAccountId`, the product from step 1, and the `productQueryId` as the
   `idempotencyKey`. Send no `mediaBuyId`. See
   [Stage returned products](https://docs.apostra.com/v2/setup/v3/buyer-workflows.md#stage-returned-products).
4. Launch it. Call `save_campaign` with `desiredPhase: "active"`. The preview
   lists the new draft buy, and the confirming call launches it. A campaign that
   is already active can be launched again to dispatch its newly staged draft
   buys. See
   [Launch explicitly](https://docs.apostra.com/v2/setup/v3/buyer-workflows.md#6-launch-explicitly).

```json theme={null}
{
  "name": "save_media_buy",
  "arguments": {
    "campaignId": "CAMPAIGN_ID",
    "sellerAccountId": 2192,
    "products": [
      {
        "productId": "QUALIFIED_PRODUCT_ID",
        "pricingOptionId": "RETURNED_PRICING_OPTION_ID",
        "budget": 5000
      }
    ],
    "idempotencyKey": "PRODUCT_QUERY_ID"
  }
}
```

### What the create accepts

* **The `idempotencyKey` is the `productQueryId`, not a key you choose.** A
  create reads it as the search round the products came from. A key that is not
  a `productQueryId` this account received returns `PRODUCT_QUERY_NOT_FOUND`.
  One `productQueryId` stages one create on a campaign, so put every product you
  want from that round in one `products` list.
* **Either product id works.** Send the qualified `sf1:` or `sf2:` id exactly as
  discovery returned it, or the seller's own `wh:` id with the `sellerAccountId`
  (and the product's `inventorySourceId`, when the search returned one). Both
  stage the same product, and both are the same request for retries.
* **A product id from an earlier read still matches.** A seller that returns
  each product under a new id on every discovery run, such as Snap, gives a
  proposal's product and the same product in a later seller products read two
  different ids. A create matches the id you send to the product in the
  `productQueryId` round when the two are the same product for the same seller
  account, and stages the round's own id. If it matches none, or more than one,
  the create is refused with a `VALIDATION_ERROR` that names the products it
  could not resolve; call `request_proposals`, or `get` with `kind: "seller"`
  and `include: ["products"]`, and send the ids together with the
  `productQueryId` that call returns.
* **Use the round that launched the campaign, or search again.** Launching a
  campaign completes its search round. You can add a further separate buy from
  that same round, as long as the campaign is live (`ACTIVE`). A round belongs to
  one campaign: a round that launched or already feeds a different campaign is
  refused, and so is a campaign that is paused or ended. A round that has
  completed for any other reason is refused too. In each case, search again and
  use the new `productQueryId`.
* **A refused create can be retried under the same key.** A create refused
  before anything was staged is not recorded, so fix the request and send it
  again with the same `productQueryId`.

### What a separate buy means for you

* **It has its own id, flight, budget and packages.** You set its pacing and read
  its delivery separately from the live buy. `get_delivery` reports each media
  buy on its own.
* **It has its own approval.** It starts as a draft, launches when you confirm
  the campaign launch, and can then wait for the seller before it delivers. Its
  phase says where it is.
* **It does not change the live buy.** The live buy keeps delivering on the
  terms it had. Nothing about it is edited, paused or replaced.

If you only want more money on a product that is already on the live buy, raise
that line item's budget instead of creating a second buy.

## What you see while the seller decides

A change to a live buy has to reach the seller, so the seller decides what it
accepts. The call waits for the seller's answer, and a change that is not live
yet is labelled as waiting, never as done.

**A pending version.** When a change is accepted but the seller has not applied
it, the call returns `action: "pending_approval"`. The buy keeps delivering on
its live values, and the waiting change appears as `pendingChange` on
`get` with `kind: "media_buy"`. `pendingAt` says whether the storefront
operator or the seller's sales agent has it. Do not send the change again, and do
not tell the buyer it is done, while `pendingChange` is there. See
[A change that is not live yet](https://docs.apostra.com/v2/setup/v3/buyer-workflows.md#a-change-that-is-not-live-yet).

**A seller that refuses or cannot confirm.** The call returns an error with
`details.mutation_outcome`, which says whether the change may have been applied.
Read the buy before sending anything again. See
[When a seller does not apply a change](https://docs.apostra.com/v2/setup/v3/buyer-workflows.md#when-a-seller-does-not-apply-a-change).

**Revisions and `CONFLICT`.** Three things go by these names, and they are
different:

* A campaign has a `revision`. `save_campaign` takes it as `expectedRevision`,
  and a stale one returns `REVISION_CONFLICT`. Read the campaign, check the
  change still applies, and send it again with the current revision.
* A storefront numbers every change to a media buy with its own `revision`, and
  [Media buy history](https://docs.apostra.com/v3/media-buy-history.md) lists them. `save_media_buy` does
  not take a media buy revision, so you cannot cite one on a change today.
* A seller can refuse a change to a media buy because it changed the buy after
  the version Apostra last read. Apostra reads the buy again and retries once
  when your change does not overlap. When it does, or Apostra cannot tell, you get
  a `CONFLICT`: the seller that refused did not apply the change. Read the buy,
  decide whether your change still applies, and send it again if it does. See
  [A seller changed the media buy](https://docs.apostra.com/v3/errors.md#a-seller-changed-the-media-buy).

## Related

* [Buyer workflows](https://docs.apostra.com/v2/setup/v3/buyer-workflows.md): the full buyer path from
  campaign to delivery.
* [Does your buy still match the booking?](https://docs.apostra.com/v3/booking-answer.md): whether the
  seller's buy still matches what you booked.
* [Errors](https://docs.apostra.com/v3/errors.md): how errors are reported.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.