> ## 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 spend with the same seller on a live campaign 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, you cannot add a product to it. To put
more inventory from the same seller on a live campaign, add a separate media buy
to the campaign. This page says what you can still change on the live buy, how
to add the separate one, 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. |
| 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 a bid | `products[].bidPrice` | Auction line items only. |
| Rename it | `name` | Only on some platforms, and only after the seller confirms. |

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).

Other changes are refused, and nothing is applied:

* **Adding a product** returns `VALIDATION_ERROR` on `products`. A product that
  is not already on the buy is not a change to that buy.
* **Removing a product** (`remove: true`) is allowed on a draft only.
* **Changing targeting** is allowed on a draft only. To change it on a buy that
  has left draft, create a new buy with the targeting you want.
* **Moving a line item to another source or seller route** returns
  `NOT_IMPLEMENTED` naming the field.

## Spend more with the same seller on a live campaign

To add a product from a 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. 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 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.