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:
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
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,
Pause, resume, or cancel one media buy
and
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:
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.
- Adding a product returns
ACTION_NOT_ALLOWEDwhen the seller does not take it, the buy has no single storefront to send it through (liveChanges.addProductsisnot_accepted), or the seller has declared nothing.details.mutation_outcomeisnot_dispatched,details.reasonisseller_does_not_acceptorseller_declared_no_actions, anddetails.recoveryiscreate_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.removeProductssays whether the seller takes it, from theremove_packagesaction it declared. When it does, Apostra sends the removal to the seller as a package cancellation (canceled: trueon 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 aspending_approvaland 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, andlineItemRefwhen 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 asSERVICE_UNAVAILABLEwithmutation_outcome: "not_dispatched": nothing was sent, so retry it. When the seller does not take it, or has declared nothing, the call returnsACTION_NOT_ALLOWEDwithdetails.mutation_outcomenot_dispatched,details.actionremove_packagesanddetails.reasonseller_does_not_acceptorseller_declared_no_actions, and nothing is sent. When the seller refuses after the send,details.reasonisseller_refusedanddetails.seller_codeis its code, such asNOT_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_ALLOWEDwithdetails.actionupdate_budgetwhen the seller does not take it (liveChanges.changeBudgetisnot_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_ALLOWEDwhen the seller does not take it (liveChanges.changeTargetingisnot_accepted) or has declared nothing.details.mutation_outcomeisnot_dispatched,details.actionisupdate_targetinganddetails.reasonisseller_does_not_acceptorseller_declared_no_actions. To get the targeting you want anyway, create a new buy with it. - Changing a frequency cap returns
ACTION_NOT_ALLOWEDthe same way, withdetails.actionupdate_frequency_caps, whenliveChanges.changeFrequencyCapisnot_acceptedor 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_ALLOWEDwhenliveChanges.changePacingisnot_acceptedor the seller has declared nothing. It speaks AdCP’s own refusal:details.attempted_actionanddetails.actionareupdate_pacing,details.reasonisnot_supported_on_buyanddetails.mutation_outcomeisnot_dispatched. - Assigning or removing a creative is refused when the seller declared what
it takes for this buy and left the change out (
liveChanges.assignCreativesorremoveCreativesisnot_accepted). The refusal is onsave_creative. - Moving a line item to another source or seller route returns
NOT_IMPLEMENTEDnaming the field.
Add a product to a live buy
WhenliveChanges.addProducts is accepted, conditional or
needs_seller_approval, send the product to the live buy:
- 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,nameor a change to a product already on the buy returnsVALIDATION_ERRORonproductsand nothing is sent.pricingOptionIdandbudgetare required, andbidPriceis optional.targetingOverlayandperformanceStandardsare not supported on an added product and returnNOT_IMPLEMENTEDnaming 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 returnsaction: "pending_approval": the live buy keeps running on what it had, the waiting add shows aspendingChange, and you should not send it again. A seller that refuses the add itself returnsACTION_NOT_ALLOWEDwithdetails.reasonseller_refusedanddetails.recoverycreate_separate_media_buy; the buy is left as it was. - A seller that has declared nothing is not asked. Where
liveChangesis absent the add is refused withseller_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
pausedflag or start and end dates of its own.
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
pausedflag, 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.
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 withproductId, 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
pausedflag, 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 you are the seller
A seller whose buy declaresadd_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
WhenliveChanges.changeTargeting is accepted, conditional or
needs_seller_approval, send the new targeting on the line item:
- 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 tonullis 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,nameor any other change to a product returnsVALIDATION_ERRORonproductswithdetails.mutation_outcomenot_dispatched. - A frequency cap is its own change, decided by its own action. A
targetingOverlay.frequency_capis sent the same way as targeting, on the line item, and goes to the same open packages. The seller decides it byliveChanges.changeFrequencyCap(itsupdate_frequency_capsaction), not bychangeTargeting. An overlay that carries both a frequency cap and another targeting dimension needs both answers to be other thannot_accepted, and is refused on the first that is.nullclears 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 returnsaction: "pending_approval": the live buy keeps running on its current targeting, the waiting change shows aspendingChange, and you should not send it again. A seller that refuses the change itself returnsACTION_NOT_ALLOWEDwithdetails.actionupdate_targetinganddetails.reasonseller_refused; the buy is left as it was. - A seller that has declared nothing is not asked. Where
liveChangesis absent the change is refused withseller_declared_no_actions.
Change pacing on a live buy
WhenliveChanges.changePacing is accepted, conditional or
needs_seller_approval, send the new pacing on the line item:
- The values are AdCP’s own:
even,asaporfront_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_buypackages[].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 returnsNOT_IMPLEMENTEDnamingproducts[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,nameor any other change to a product, which returnsVALIDATION_ERRORonproducts. - The seller decides. The result is
action: "updated"once applied, oraction: "pending_approval"while the seller has it and has not applied it (the buy keeps its current pacing and the change shows aspendingChange; do not send it again). A seller that refuses a change it took returnsACTION_NOT_ALLOWEDwithdetails.reasonseller_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, andproducts[].pacingon a create returnsVALIDATION_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 withsave_creative, by changing the campaigns the creative runs on:
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 declaresremove_creative.liveChanges.assignCreativesandliveChanges.removeCreativeson each buy report the seller’s answer, from the same code the write uses.replace_creativeis 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_creativereturnsACTION_NOT_ALLOWEDwith AdCP’s own reason,details.reason: "not_supported_on_buy",details.attempted_actionupdate_creative_assignmentsorremove_creative,details.mediaBuyIdanddetails.campaignId, anddetails.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_creativereturnsliveMediaBuyswith 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 aspendingChangeongetwithkind: "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 whose
originisadcp; a storefront whose inventory runs through a platform adapter does not return that history yet. The membership write isCONFLICT-safe: another change to the same creative or campaign in flight returnsCONFLICT, and a membership that changed while the request was prepared returnsCONFLICTtoo. Read the creative and send the full set again. Repeating the samecampaignIdschanges nothing. - The campaign side follows the same rule.
save_campaignwithcreativeIdsreplaces 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 isACTION_NOT_ALLOWEDwith the same AdCP details, oncreativeIds, and no creative is attached or detached. Becausesave_campaigncan also change other campaign fields in the same call, a refusal there can come after those changes were saved: the error says so withpartialWriteand “prior changes were already saved”. To be sure nothing else is saved, sendcreativeIdson 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_reelsandmeta_existing_postcan 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.removeCreativesisnot_accepted), so detaching a creative from a campaign with a running Meta buy is refused withnot_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.- Find the product. Use
searchwithkind: "wholesale_product"orrequest_proposals. Keep every identity field it returns and itsproductQueryId. - 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_ERRORthat names the products it could not fund. To spend more in total, raise the campaign budget first withsave_campaign. - Stage the buy:
save_media_buywith thecampaignId, the seller’ssellerAccountId, the product from step 1, and theproductQueryIdas theidempotencyKey. Send nomediaBuyId. See Stage returned products. - Launch it. Call
save_campaignwithdesiredPhase: "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 the create accepts
- The
idempotencyKeyis theproductQueryId, not a key you choose. A create reads it as the search round the products came from. A key that is not aproductQueryIdthis account received returnsPRODUCT_QUERY_NOT_FOUND. OneproductQueryIdstages one create on a campaign, so put every product you want from that round in oneproductslist. - Either product id works. Send the qualified
sf1:orsf2:id exactly as discovery returned it, or the seller’s ownwh:id with thesellerAccountId(and the product’sinventorySourceId, 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
productQueryIdround 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 aVALIDATION_ERRORthat names the products it could not resolve; callrequest_proposals, orgetwithkind: "seller"andinclude: ["products"], and send the ids together with theproductQueryIdthat 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 newproductQueryId. - 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_deliveryreports 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.
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 returnsaction: "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_campaigntakes it asexpectedRevision, and a stale one returnsREVISION_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_buydoes 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.
Related
- Buyer workflows: the full buyer path from campaign to delivery.
- Does your buy still match the booking?: whether the seller’s buy still matches what you booked.
- Errors: how errors are reported.