Skip to main content
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.
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: The buyer workflow guide has the rules and examples for each one: Change a live media buy, Pause, resume, or cancel one media buy and 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.
  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.

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