Start with seller discovery
To practise without credentials, use the local planning exercise. It checks fictional data and produces a local receipt; it does not complete the connected steps below.- Connect an MCP client to
/mcp/v3and authenticate. - Call
get_status; verify the intended Buyer Account before using its data. - Read
tools/listand expose only the tools your prototype needs to its model. - Call
searchwith{"kind":"seller","limit":10}. Follow returned cursors if you need the complete list. - Display the sellers and their returned readiness and connection information. Keep missing or blocked states visible.
request_proposals is a later
step that sends a campaign brief to the eligible seller cohort. It should run
only when the user has asked your application to start that buying workflow.
Use the structured result for IDs and readiness. A model can explain the result
but should not reconstruct qualified identifiers or extract them from prose.
Connect a seller when the workflow needs it
Read the selected seller’s connection and activation state before requesting offers. Usesearch or get for existing connection records and the current
save_connection schema for the required selection, billing, authorization,
provider-account choice, or advertiser mapping. An authorization action returns
a browser URL; provider credentials do not belong in the tool arguments.
After the person completes any required browser step, re-read the seller and
connection. A listed seller is not necessarily ready for this advertiser to
buy from. The buyer workflow explains these
readiness checks before campaign authoring and proposal requests.
For one advertiser, call get with kind: "seller", the seller id, and
advertiserId, or pass filter.advertiserId to search for sellers. The
returned controlPlane.activation.state, requiredAction, and advertisers
describe only that advertiser. An active advertiser is ready at the activation
step even when another advertiser still needs setup. Its own missing setup,
pending seller approval, or missing grant still appears in its activation.
If no activation record exists for the requested advertiser, the state is
inactive and advertisers is empty; this does not establish readiness.
Omit advertiser scope to read the account-wide activation summary and all its
advertiser rows. Account selection and billing remain account-wide on both
reads. Activation readiness does not guarantee that a proposal request will
return products or that every booking requirement has been met.
Give the loop a durable owner
For a production hybrid application, keep these records outside the model’s conversation:
The loop is:
Application code validates the model’s proposed tool and arguments against the
current schema and your allowed actions. Stop a run when it needs a person,
is waiting on asynchronous work, has reached its call budget, or has no valid
next step. A scheduled worker or a supported notification can resume it later.
Add buying steps
Confirm the brief before you save it
What you send asbrief is what every seller reads at discovery, so a buyer’s
request is not automatically a brief. Pull the structured fields out of what
they said — name, advertiser, flight, budget and currency, channels — and set
them as fields. Then show the brief you intend to save, ask whether to expand
or refine it (target audience, the KPIs success is judged on, creative
messaging themes), and save what the buyer agrees to with
briefConfirmed: true.
briefConfirmed is optional and nothing is refused without it. A save that
sets a brief without it comes back with a warning saying the brief was taken
as sent; the campaign is still a draft at that point, so the brief can be
refined before request_proposals sends it anywhere. A retry of the same
idempotencyKey reports the same warning, so the note survives a lost
response. A retry answers with the campaign the first call created and the
brief it stored, so briefConfirmed: true clears the warning there only when
it is sent with that same text; confirming different words says nothing about
the brief the response carries. Text the buyer gives you as a brief goes in
verbatim either way — confirming asks whether the words are the brief, it
never summarises them.
An update warns only when it puts new words in front of sellers: a brief that
differs from the stored one. Re-sending the stored brief beside another field
change, or clearing it with brief: null, confirms nothing and is not asked
about.
The next step after a campaign is created
A new campaign has no products, so discovery is not optional.save_media_buy
needs a productId and a productQueryId, and only request_proposals
returns them, so a media buy staged straight after a campaign is created is
refused. That is why the create result names discovery as the next step and
nothing else. The buyer still sees what came back and selects before a buy is
staged.
Discovery has its own prerequisites, so nextStep says whether the campaign
has met them rather than promising a call that would be refused:
ready step’s arguments as given, with your own idempotencyKey. A
needs_input step lists each thing still missing and the tool that supplies
it, then leads to the same discovery call:
market— the campaign names no country. A seller is never asked to infer the market from brief prose, so set one before requesting proposals, withsave_campaignandtargetingOverlay.geo_countries(orgeo_regions,geo_metros).seller_choice— the campaign carries no seller list, so a round has no cohort. PasssellerAccountIdstorequest_proposals, orconfirmBroadcast: trueonce the buyer has confirmed a round to every eligible seller. The choice is the buyer’s, so the server never makes it for them andnextStepnever sendsconfirmBroadcast.
nextStep at all when the seller capability
read was down at the time: the round would refuse the call right then, so the
server names no step rather than one that is failing. Read the campaign again
before requesting proposals.
wholesale_catalogue is the answer when every seller on the campaign sells
wholesale only. Those sellers take no brief, so request_proposals refuses
such a round outright with SELLER_WHOLESALE_ONLY; their products come from
search with kind: "wholesale_product" instead, and you book what the buyer
picks with save_media_buy. The step carries no arguments, because that
search needs the sellers’ Account ids and the campaign’s channels and
countries: the Next: line names each one.
ready says the campaign’s own inputs are complete. It does not promise the
round will succeed: seller eligibility, your round allowance, another round
already running for this buyer, and a revision that moved since the create are
all answered when the round is dispatched. A refusal there is a real answer
about the market or the sellers, not a broken step.
What a retried create replays depends on how you call it. Over the HTTP API, a
retry with the same Idempotency-Key returns the stored response verbatim,
marked Idempotency-Replayed: true, so its nextStep still carries the
revision the first create saw: if anything has changed the campaign since, read
the current revision with get (kind: "campaign") before sending those
arguments. Calling the tool over MCP with the same idempotencyKey returns the
campaign as it stands now and recomputes nextStep from it, so its revision and
its ready or needs_input status are current and you can send the arguments
as given.
Campaign reads and campaign search text label a flight in the advertiser’s
current default timezone and in UTC. The returned flight.startAt and
flight.endAt values remain the stored UTC instants. If the advertiser timezone
cannot be read, the text labels the UTC window instead.
The launch preview and confirmation use separate idempotency keys. If the
campaign changes after approval, obtain a fresh preview and approval rather
than confirming a different draft. Content approval, seller creative review,
and launch approval are separate decisions.
On a buyer account with spend approval
on, the confirm returns approval_required instead of launching. Nothing has
been sent to a seller: the launch is recorded for an administrator to approve
on the Apostra site, and the result carries the approval’s link and expiry.
Show the person the link, then repeat the confirm with the same
idempotencyKey to read the outcome. Once approved, the launch runs exactly as
recorded; if the campaign’s revision or what its media buys would spend changed
in the meantime, the approval fails and nothing is booked, so preview and
confirm again. Read account.requireSpendApproval on get_status to know
beforehand.
A launch can fail after you confirm it. If it failed because a creative was
refused and only you can change that, Apostra does not retry it: fix the cause
the error names and confirm the launch again straight away. If it failed for a
reason that may clear by itself, such as a seller that could not be reached,
Apostra sends it again on its own, up to five attempts, and confirming the launch
meanwhile returns CONFLICT with details.reason LAUNCH_IN_FLIGHT. That
refusal names the launch and its status, and details.retryAfter says when it
is sent again. Confirm again after that time: the launch has either gone through
or run out of attempts and been released.
Campaign get returns the saved targetingOverlay in its structured object
and text response without an include. For example, saving
targetingOverlay: { geo_countries: ["US"], language: ["en"] } lets you
read back both constraints at the saved revision. An unset or cleared overlay
is omitted from the object and reported as not set in text. Campaign search
returns summaries; use the campaign ID from a result to read targeting with
get. The campaign overlay records campaign intent. It does not confirm that
each media buy or seller has applied those settings.
get with kind: "media_buy" and include: ["products"] returns each
package’s effective targeting_overlay, including placement_selection and
every other dimension accepted on save_media_buy.products[].targetingOverlay,
in both the structured object and the text response. This reflects what was
requested, filled in with the buyer’s own request wherever the seller’s own
readback is silent on a dimension — it is not independent confirmation that
the seller’s live ad-set state matches. A seller that confirms targeting
server-side overrides the buyer’s requested value for that dimension. The
fill-in happens when a package is written (on create, on update, or on a
routine status sync): a package with no write since this behavior shipped may
still omit a dimension the seller’s own readback does not report until its
next write.
When a buyer sets targetingOverlay.demographics.age, send kind: "minimum",
"maximum", or "range" to match the supplied bound fields. Campaign bidding
also requires kind: "cost_per" or "roas", and every channelGroups item
requires kind: "preset" or "custom". These are closed request variants:
send only the fields for the selected kind.
Discovery results belong to the buyer account
Every product a buyer finds through a storefront, whether the storefront hosts the seller or an external seller sits behind it, and whether it arrives throughrequest_proposals, search, or get_products, is saved to that buyer’s
account. Prices and product details are account-specific, so a buyer never sees
another buyer’s products. A product is staged only from the buyer’s own saved
results, so a selection that predates them must be found again first.
Resume a proposal request
A freshrequest_proposals call durably schedules seller discovery. It
normally returns running. Persist the original campaign revision and
idempotency key before making the call, then repeat that same request until
its status is complete, partial, or failed.
Once terminal, follow every page.nextCursor using the documented continuation
arguments. One seller can span several result pages. A partial result is not
permission to discard failed seller outcomes, and the first page is not the
whole result.
Only one proposal execution can run per buyer across campaigns. A new key
starts a new round; it is not a polling mechanism. See
Request proposals.
Sellers are asked as the campaign’s advertiser’s own account with each seller.
A seller where the advertiser has no active account is not contacted. When you
did not name sellers, those sellers are only counted: if none qualifies, the
round fails with NO_ELIGIBLE_SELLERS and says how many are still setting up
the advertiser’s account and how many need attention. When you named a seller,
its perSeller result carries outcome.kind: "skipped" with reasonCode
account_pending (setup is on its way), account_needs_attention (the buyer,
an operator or the seller has to act; the message points to Media Partners).
When the media partner’s own sales agent holds your accounts and has not approved
one for the advertiser yet, the perSeller message says approving it is the
media partner’s step and that there is nothing for you to map or change; it does
not send you to Media Partners. A media partner left uncalled for another reason
we recorded, such as its account for you not being active yet, is skipped with
reasonCode eligibility and NO_ELIGIBLE_SELLERS, and the message names that
reason.
A round queued before requests recorded who sent them cannot present a company
account, so each such seller is skipped with reasonCode
round_predates_account_rule and the message says to run the request again.
A seller closed to buyers keeps eligibility instead of an account reason,
including a closed seller named by a buyer that seller sponsors.
If the buyer has not finished setup, the round fails with
BUYER_SETUP_REQUIRED and names the step; that failure is final, so complete the
step and request again.
The rule is the same for product discovery through search and get; see
Get products across storefronts.
When you read one seller’s products with
get({ kind: "seller", id, advertiserId, include: ["products"] }) and the
advertiser has no active account with that seller, the seller’s
catalog.ext.interchange.storefront_results[] row is skipped with
reason_code account_pending (setup is on its way, nothing to do) or
account_needs_attention (the buyer, an operator or the seller has to act), and
a suggestion that points to Media Partners. The text says the same on a
Not searched line. A seller that answers a wholesale browse by saying your
advertiser’s account needs setup is reported the same way by
search({ kind: "wholesale_product" }), as finished with account_needs_attention
rather than partial. get of one of its products returns BUYER_SETUP_REQUIRED
with that reason in details.reason, not NOT_FOUND.
Platform sellers sell wholesale only
Sellers that sell through an ad platform (Meta, TikTok, Snap, Spotify, Pinterest, Reddit, LinkedIn, Google, Amazon and OpenAI Ads) sell their catalogue wholesale only. They take no proposals and do not search their catalogue from a brief, and theirget_adcp_capabilities declares
media_buy.buying_modes: ["wholesale"].
request_proposalsdoes not ask them, because a brief gets proposals back. It lists each one inskippedSellerswith the reasonwholesale_only, and refuses a round that names only such sellers withSELLER_WHOLESALE_ONLY.- A
get_productscall with a brief is refused withUNSUPPORTED_FEATUREanddetails.reasonbrief_mode_unavailable. Sendbuying_mode: "wholesale"with no brief instead. - Browse their products with
search({ kind: "wholesale_product", filter: { advertiserId } }), narrowed withsellerAccountIds,channelandcountriesto the campaign, and book the ones you pick withsave_media_buy, using the search’sproductQueryIdas the idempotency key. These are the seller’s standard products at its listed prices, not products chosen for a brief. - They do not declare sandbox support, because they create real campaigns and
spend at the platform. A sandbox advertiser’s buy on one is refused with
details.reasonsandbox_buy_refused_for_adapterbefore anything reaches the platform. To test a platform seller, buy with a live advertiser. - They offer only the tools they implement. Event sources, audience sync,
catalogs and signals differ by platform, so read the seller’s tool list and
get_adcp_capabilitiesinstead of assuming them. A seller with noget_signalsdoes not list it and does not declare thesignalsprotocol.
Video placement types on a product
A seller that says where a product’s video ads play gives the product AdCP’svideo_placement_types: one or more of instream,
accompanying_content, interstitial and standalone, as the
OpenRTB 2.6 plcmt definitions. A product that declares none leaves the
field out.
In a wholesale get_products call, send filters.video_placement_types to
get only the products whose declared types include at least one you ask for. A
product that declares none does not match. In a brief call, Apostra passes
the filter on to the sellers it relays the request to. Products Apostra
composes from a seller’s inventory do not carry placement types yet, so the
filter does not narrow them.
Synthetic sellers say so on every proposal product
Some sellers serve synthetic sample inventory instead of a real publisher’s: a Demo Storefront, and the Apostra synthetic seller that exists for agent demos and checks. Such a seller’s data is not suitable for commercial decisions. When you read a proposal withget({ kind: "proposal", id, include: ["products"] }),
each product row from a synthetic seller carries
synthetic: { label, disclosure }, and the text of the read repeats the
disclosure. The field is absent for every other seller. Show the disclosure to
whoever reads the result.
If Apostra cannot tell whether the seller is synthetic when you read the
products, the read fails with SERVICE_UNAVAILABLE and returns no products;
read it again in a moment.
When the request comes from a sandbox account, a synthetic seller also sets
AdCP’s own sandbox: true on its get_products and request_proposals
responses, which AdCP defines as “this response contains simulated data from
sandbox mode”. A request from a live account gets no such flag from the same
seller, and no other seller sets it on Apostra’s behalf: the flag says the
response is simulated, and only a synthetic seller’s responses are.
Prototype against the synthetic seller in a sandbox, with no billing
You can request proposals from the Apostra synthetic seller without billing details, payment terms or a payment method, as long as the campaign’s advertiser is a sandbox advertiser. A sandbox request spends nothing, so Apostra does not ask the buyer to set up payment first. Sandbox briefs to the synthetic seller and to Demo Storefronts also do not count against the daily limit on sandbox briefs, so you can run your agent against them as often as you need (sandbox brief limit). This is a sandbox rule, not a general one. A live advertiser still needs the buyer’s billing details before a seller that bills through Apostra is asked for a proposal, so that no seller quotes a buyer it cannot bill. When the sellers on a live campaign are not eligible for that reason,request_proposals returns
CAMPAIGN_SELLERS_INELIGIBLE and names them.
The sandbox exception reaches only sellers that declare sandbox support, which
is AdCP’s account.sandbox capability in get_adcp_capabilities. The Apostra
synthetic seller and every Demo Storefront declare it, because everything they
sell is synthetic. A seller that does not declare it is never asked for a
proposal on behalf of a sandbox advertiser: it stays out of the round and, if
you named it, request_proposals returns CAMPAIGN_SELLERS_INELIGIBLE. Real
publishers’ sellers ask for billing details on live advertisers, and most do not
declare sandbox support, so a sandbox prototype that works against the
synthetic seller does not show that a real seller will take the request.
To try it, create an advertiser with sandbox: true, switch the synthetic
seller on for it, save a campaign, and call request_proposals. Setup other
than payment still applies: the Terms of Service accepted, a plan selected and a
verified organization identity.
See what each seller was told
When you request proposals, Apostra sends each seller a brief made from your campaign, keeping back what that seller does not need, such as your total budget. To see exactly what one seller was sent, read its proposal withget({ kind: "proposal", id, include: ["brief"] }). brief.request is the
brief as it was sent, frozen at that moment: the campaign name and outcome,
flight, geo, demographics, channels, language, devices, formats, audience
references and goals, with null for anything not sent. brief.withheldCategories
names what was kept back. A later change to the campaign does not change a
brief already sent, so compare it with the current campaign to see what has
moved. If the brief was too large to keep, brief.complete is false and
brief.request is null.
Recover from interrupted writes
A timeout or disconnected MCP session does not prove a write failed. Preserve the request, inspect any structured error andpartialWrite evidence, and
re-read the affected object before retrying. Reuse an idempotency key only for
the same logical operation and unchanged arguments. Follow a tool’s specific
contract where it supplies its own identity, such as the productQueryId used
when staging returned products.
Connections and individual tool calls have time limits and can be interrupted
by deployments. A workflow that spans creative review or seller execution must
survive reconnection. See Client setup and
Capability limits.
Give independent software its own identity
An interactive assistant using a person’s OAuth connection requires no buyer-agent registration. For independently operated software, an organization administrator can register an external buyer agent, issue its credential, and grant exact advertiser access through buyer-agent management. These controls require the documented direct administrator session. Where the current catalog advertisessave_buyer_agent, use it with the matching
get/search reads. Use the documented console or REST path for controls the
active v3 catalog does not expose. Do not assume a runtime credential can
register itself or grant its own advertiser access. Registration gives software
an identity; it does not make Apostra the hosted runtime for that software.