Open the Page
V3 opens it withopen_media_buys_page. Both fields are optional.
accountRelationshipId focuses one seller-owned account relationship.
sellerAccountMappingId instead focuses one company-owned seller account
mapping (never both); it is the ID of that mapping, not a seller’s Account id.
Its earlier name, sellerAccountId, still works and is being retired.
view is media_buys (the default), creatives or delivery. Only a Seller
Account can open the Page; a Buyer Account is refused with a wrong-account
error. In the Apostra web app, the same Page opens from Operate, then
Media buys, and it is the first page a live seller sees.
Before a buy reaches approval
For a buy that uses a managed ad server, the buyer’s targeting can be checked before it reaches your approval queue. If the ad server cannot represent that targeting, the buyer sees a clear reason and can correct the request. You do not need to act because no approval item is created. If that check is temporarily unavailable, the buy still reaches approval as usual; approving it does not bypass the later delivery check.A buy whose flight ends before you decide
A new buy that is still waiting for your approval when its flight ends can no longer run. Apostra rejects it for you within a few minutes of the flight end, closes its approval item, and tells the buyer the flight ended before the buy was approved. The buyer can submit a new buy with current dates. This does not happen while your storefront is paused for new business.What a row says
Each row shows the buyer, the lifecycle status, a problem status, one problem line, and the flight dates. A buy Apostra placed to certify your agent is listed too, and its next action starts “Certification buy from Apostra, not a buyer’s order.” See Certification. The problem status is a coloured dot and one line:
The lifecycle status follows what the seller’s own status read reports for the
buy (pending, active, paused or ended), not the status in its delivery report.
Some sellers derive a delivery report’s status from flight dates alone, so it
can say active for a buy that has not started. When delivery shows impressions
or spend while the seller’s status read says the buy is not live, the row keeps
the status read’s status and Apostra’s operations team is alerted to ask the
seller which is right. See a buy’s status follows the seller’s own status
read.
For a modular source that needs you to create the upstream booking, the status
label says Booking required, the detail says Upstream booking requires
seller action, and the next action keeps the booking task separate from any
creative work. After you complete the booking, if the source cannot report its
own live status, the label says Booked upstream and the detail says
Booked upstream; start not independently verified. Apostra does not call
that buy active or say it will start automatically. If the source does report
status, that provider-reported status remains authoritative.
A buy with nothing flagged reads On track in grey rather than green: green
on a list of work would be decoration. Not having enough data to judge is also
grey, never red. The page works none of this out itself; the status, its
colour and the problem line all come from the same attention reading the rest
of the platform uses. The problem line is the strongest flag on the buy, and
it names the measure and its units, for example “Cost per click is $3.60,
against the buyer's $3.00 target”.
The first page of the list is ranked server-side by what needs you: money the
flight will not deliver, then work waiting on you, then a goal being missed,
then everything else. Later pages return to the stable urgency order, so a page
is never evidence of your worst buys across the storefront.
Open a row
Select a row to open it in place. The opened row holds what the collapsed row leaves out and answers two questions. It opens on what the buy is: a line naming the operator, its creatives, how many sources it fans out to, how it is billed, and the ids below; then the budget, the rate it was booked at and how far the flight has run as figures. Anything waiting on someone — a flag, who owes the next move, why a buy is stuck — follows underneath. A buy that needs nothing from anyone says nothing there.The ids on a buy
A buy carries at most two ids: one that names the buy here, and — when it can be named — the one your own source holds for it.
Seller id appears only when exactly one source can name it. A buy that fans
out to several sources has one id per source and none of them is the buy’s, so
none is shown rather than presenting one source’s id as the whole buy’s. It is
also absent before any source has reported one, and on a buy your ad server
manages, whose Ad server id is already your source’s own id.
Pacing. The spend delivered so far against what the delivery schedule
expects by now, drawn as one bar per measure: the fill is what
delivered and a marker is where the schedule expects it, so the shortfall is
the distance between them. Beside the heading is the pace verdict: on pace,
behind or ahead. How much of the flight has run, and the daily spend against
the daily rate that finishes on budget, sit with the figures above. Delivery is
shown in the unit the buy was booked and priced in: expected against delivered
impressions for a buy booked at a CPM, clicks for a cost per click, views for a
cost per view and completed views for a cost per completed view. The unit and
the expected quantity come from the fixed price the buy was booked at, never a
guess: the budget divided by that price is what the buy should deliver over the
whole flight, and the delivery schedule sets its expected share by now. A buy with no
fixed price on record (an auction line), lines priced differently from one
another, a price on something delivery does not count (cost per action, viewable
CPM, rating points or a flat fee) or a price in a different currency from the
budget shows what was delivered and says why there is nothing to compare it
with. A buy booked at $0, such as donated media, has no spend to pace: in place
of the spend bar it shows delivered impressions against the impressions goal it
was booked with, using the same schedule to set its expected share by now.
Routed buys use the pacing curve sent to the seller; when no curve is available,
the schedule defaults to even. A buy paced as fast as possible has no pace bar.
When there is
no verdict, the Page says why (no booked budget, no flight dates, the flight
has not started, too little of the flight reported, or no spend reported) and
draws no bar. A buy nothing has reported for keeps the section and reads
“Nothing has been reported for this buy yet”, never zero, and a count the
source did not report reads “Not reported”.
The buyer’s goal, headed by what it measures (for example “Cost per
click”) with its verdict beside it: the buyer’s target, what you committed to (guaranteed, best effort
or report-only), the delivered value, the verdict, who counted it and how
fresh the numbers are. The badge on the verdict takes the same colour as the
row’s dot. A goal a measurement vendor counts names the vendor by its domain.
When you cannot see the vendor’s numbers, the Page shows the score the buyer’s
side reported to you and no delivered value. A buy whose goal was never sent to
you keeps the section and says so. When there is too little delivery to judge fairly, it reads “Too
early to call”.
A routed buy’s opened row has an Open full timeline button for the per-buy
timeline. A buy your ad server manages opens to the same pacing and goal but has
no timeline to open.
The timeline’s stages follow the exchange lifecycle:
received, screened,
decided, forwarded or forward_failed, submitted, source_moderation,
accepted or rejected, then delivering. screened is reserved for the
acceptance-policy pre-screen and is not emitted today. accepted means the
source accepted the transaction boundary; it does not mean the buy is
trafficked or delivered. Inbound source webhooks appear as evidence inside a
stage, never as a stage of their own, so a source that sends none is not
evidence of a problem. The forwarded and response payloads are not returned:
each source leg carries payloadHighlights (flight, budget, packages and
targeting dimensions) instead.
Each leg carries two references for different counterparties. Quote
theirReference, the source’s own ids, to the inventory source. Quote
platformReference, the create idempotency key, to the source before it has
accepted the buy and to Apostra support, always together with its
requestedAt timestamp: the key is stable across the buy’s life and requests
are not.
The full timeline’s Canonical reporting card shows reporting obligations
for the buy. When a seller statement is overdue, rejected or has
stopped progressing, the obligation names its exact seller account and
reporting period. A statement that never arrived stays missing; it never
appears as zero delivery or zero spend.
Reading the Canonical reporting card
The card is read for one buy and one buyer account together, through the Page’s app-only reporting tool, because different buyers can reuse the same media buy id. A buy that buyer account did not book on your storefront reads as not found, and so does one on a storefront you archived. It never reads as an empty report. The card’s first line gives the buy’s overall health, the time its data runs through, and the next time a report is expected. Health is one ofwaiting,
healthy, delayed, action_required or complete. A buy with no reporting
obligation reads “not configured”. Data-through reads “not reported” until an
obligation has been satisfied with a known data-through time, and next expected
reads “not scheduled” when no expected time is still ahead. The read also marks
its data current, or stale while the buy is delayed or action_required,
and leaves that empty while nothing has been reported.
Each obligation then gets one line for its reporting period:
- First report missing means no report has arrived by the time it was expected. Awaiting first report means none has arrived and it is not yet due.
- A report that has arrived shows its kind and its row count.
snapshotandofficialare the two levels of finality, andrestatementis a revision that replaces an earlier one. A report with zero rows is a real zero-row report, not a missing one. - Partial coverage or none coverage shows when the Source reports only part of the buy, or none of it. Partial coverage is never presented as whole-buy coverage. Full coverage, and coverage that was not observed, show nothing.
Read a buy’s delivery from an agent
search and get with kind: "media_buy" return a buy’s delivery when you ask
for it with include: ["deliverySummary"]. It reads the same list the Page
reads, so an agent sees the impressions and spend you see on the row. A read
without the include is unchanged. search takes one include at a time.
search, each buy carries its own deliverySummary. On get, it sits
beside object.
- The figures use AdCP’s metric names:
impressions,spend,clicks,views,completed_viewsandconversions. A count the source did not report is left out, never shown as zero. currencyis the currency the buy was booked in. A buy with no booked currency returns its counts with nospend, rather than a spend with no currency.- A routed buy’s
window.endis the last reporting day in the figures. A buy your ad server manages has nowindow, because an ad server states a running total without the day it runs through. Neither carries anasOf. deliverySummaryisnullwhen the buy has reported nothing. When Apostra could not read delivery, the read says so inwarnings, sonullis never the only sign of a failed read.- A Demo Storefront’s buys return the demo’s own figures.
get_delivery is unchanged: it reads delivery by day,
and for a seller its spend is unavailable, because seller delivery rows carry
no currency.
Read a buy’s status from an agent
search and get with kind: "media_buy" also return the buy’s lifecycle as
the buyer sees it, in two fields.
phaseis the buy’s lifecycle:draft,pendingApproval,inputRequired,active,completed,canceled,failedorrejected. It is notsellerStatus, which is your own view of the buy from approval and forwarding.isPausedistruewhile the buyer has paused the buy. A paused buy keeps theactivephase.
Decide a queued buy
You decide a queued buy,approved or rejected, from the Approvals Page or
with save_work_item. A decision can carry reviewerNotes of up to 2000
characters.
The decision is recorded before forwarding to the Sources finishes. After an
approval, a buy with no forwardedAt has not been forwarded and still needs a
retry. A forwardedAt time shows that forwarding was recorded, not that every
Source accepted the buy, so check what each Source answered before you treat
the buy as delivered.
Saving the decision a buy already has returns unchanged and keeps the
original evidence. Saving the opposite decision is refused with
DECISION_ALREADY_RECORDED: the original decision stays in place, and a
correction is a new reconciliation action, never an overwrite.
An approval is refused while the buy has a spend conflict you have not
overruled. See Overrule a spend conflict.
Decide a creative review
You decide a creative review the same way, withsave_work_item and
kind: "creative_review". Once you approve it, Apostra sends the creative to
each of your Sources that takes it, one delivery per Source. The reply to your
decision, and every later get or search of the review, report the same
downstream.state:
When the state is
unknown, evidence.outcome is one of:
ledger_unavailable: Apostra could not read the delivery state in time. Read the review again.no_delivery_request: Apostra holds no delivery for this review, so nothing was sent and reading it again will not change the answer. Ask Apostra to check the review.superseded: a newer delivery of this creative replaced this one. Read the creative’s newer review.
evidence.legs counts the deliveries in each state.
Retry a failed forward
A retry re-sends an approved buy to its sources under the same media buy id and with your original approval. You are re-sending the same decision, not making a new one, so only an approved buy can be retried: a buy you rejected has nothing to re-send. A retry reuses the buy’s idempotency key, so a source that honors keys does not book it twice. You retry from the Approvals Page, which shows a partial-success notice after a decision whose delivery to a source did not complete, or from Pending operations. Pending operations offers Retry for a failure the platform has not given up on. For a buy a source refused outright and the platform stopped retrying, it offers Re-send refused buy, but only when a source route was recorded for the buy. Apostra then refuses the re-send in two cases:- A source route already holds an upstream media-buy or task id (the refusal
reason is
upstream_buy_exists). The buy reached that source, so reconcile or cancel it in the ad server instead of sending it again. - No failed source route was recorded (
no_failed_route). The buy stopped before any source was contacted, for example because the storefront was not ready to transact, a settlement currency was not configured, or an FX quote had expired. Fix that condition and have the buyer submit a new media buy.
flight_window_elapsed; ask the buyer to submit a new media buy with a current
flight window.
Demo Storefronts
A Demo Storefront has no buyers, so its Media Buys page would be empty. While the demo is running, the page lists four generated live buys so you can see what each answer looks like: one on track, one spending behind its flight, one missing the goal its buyer set, and one with too little delivery to judge. Each generated buy is marked Synthetic beside its status and carries the demo’s notice: “Synthetic demo data only. It is unsuitable for commercial decisions.” Everything else about the row is worked out the way it is for a real buy, so the pacing, expected delivery, goal verdict and problem line are real answers to made-up numbers. A generated buy opens like any other row, but it has no Open full timeline button, because it is never stored. The generated buys exist only for the length of the demo and only on the Demo Storefront. They are made fresh each time the page is read, are never saved, never count in your delivery totals, and are never shared with other sellers or buyers. A real Storefront never lists them, and when the demo ends they are gone. They follow the page’s filters, so a filter by buyer or by a status they do not have lists none of them.Related
- Seller workflows
- Goal-seeking campaigns, for how the buyer’s goal and your commitment are recorded
- Diagnosing stuck media buys
- Source diagnostics Page