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

# Media Buys Page

> Open the seller's Media Buys Page from V3 to see which buys have a problem and why, with pacing and the buyer's goal one click away.

The Media Buys Page is the seller's operations home. It lists every buy on
your storefront, ranked by what is most likely to need you, and each row says
whether there is a problem with that buy before you open it. It is read-only:
acting on a buy happens in approvals, the retry task, or by asking Apostra.

## Open the Page

V3 opens it with `open_media_buys_page`. Both fields are optional.

```json theme={null}
{
  "accountRelationshipId": "RELATIONSHIP_ID",
  "view": "media_buys"
}
```

`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](https://docs.apostra.com/v3/certification.md). The problem status is a coloured dot and one line:

| Row says | What it means | Dot |
| - | - | - |
| Behind pace | The flight is running and spend is behind what the delivery schedule expects, so money will not deliver at the current rate | Red |
| Needs you | Something is waiting on you, or delivery needs you to act | Yellow |
| Missing the buyer's goal | The buyer's goal is behind its target | Red once the flight is running, yellow before |
| On track | Nothing is flagged | Neutral grey |

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](https://docs.apostra.com/v2/concepts/media-buy-lifecycle.md#a-buys-status-follows-the-sellers-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.

| Label | What it is |
| - | - |
| **Apostra id** | This storefront's own id for a buy routed through Apostra (`sf_mb_…`). |
| **Ad server id** | A buy your ad server manages was never routed through Apostra, so it has no Apostra id; the id shown is the one your source already had. A buy shows this *or* an Apostra id, never both. |
| **Seller id** | The id your own source holds for the buy — what you quote to your ad server. |

**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 of `waiting`,
`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. `snapshot` and
  `official` are the two levels of finality, and `restatement` is 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.

The read attributes the reporting to a Source only when an immutable
acquisition plan ties each obligation to it. When it cannot, that proof was not
observed, which does not mean the Agent cannot report. A buy whose obligations
exceed what one read can hold is marked truncated, and it returns no overall
health, data-through or freshness rather than judging from part of the ledger.

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

```json theme={null}
{ "kind": "media_buy", "include": ["deliverySummary"], "limit": 50 }
```

```json theme={null}
{ "kind": "media_buy", "id": "MEDIA_BUY_ID", "include": ["deliverySummary"] }
```

On `search`, each buy carries its own `deliverySummary`. On `get`, it sits
beside `object`.

```json theme={null}
{
  "impressions": 1250000,
  "spend": 72500,
  "currency": "USD",
  "window": { "end": "2026-08-14" }
}
```

* The figures use AdCP's metric names: `impressions`, `spend`, `clicks`,
  `views`, `completed_views` and `conversions`. A count the source did not report
  is left out, never shown as zero.
* `currency` is the currency the buy was booked in. A buy with no booked
  currency returns its counts with no `spend`, rather than a spend with no
  currency.
* A routed buy's `window.end` is the last reporting day in the figures. A buy
  your ad server manages has no `window`, because an ad server states a running
  total without the day it runs through. Neither carries an `asOf`.
* `deliverySummary` is `null` when the buy has reported nothing. When Apostra
  could not read delivery, the read says so in `warnings`, so `null` is never the
  only sign of a failed read.
* A Demo Storefront's buys return the demo's own figures.

The include does not carry pace, the goal verdict or the per-source figures;
they stay on the Page. `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.

* `phase` is the buy's lifecycle: `draft`, `pendingApproval`, `inputRequired`,
  `active`, `completed`, `canceled`, `failed` or `rejected`. It is not
  `sellerStatus`, which is your own view of the buy from approval and forwarding.
* `isPaused` is `true` while the buyer has paused the buy. A paused buy keeps
  the `active` phase.

Both fields are left out when the buy has no record on the buyer's side, such as
a buy a third party placed directly with your Storefront or a buy your ad
server manages. No budget comes with them: you see the net amount you are
authorized for, never the buyer's gross budget.

## 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](https://docs.apostra.com/v3/agreed-terms-check.md#overrule-a-spend-conflict).

## Decide a creative review

You decide a creative review the same way, with `save_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`:

| State | What it means |
| - | - |
| `complete` | Every Source that takes the creative accepted it. |
| `in_progress` | A delivery is still being sent, or the buy's Sources are not set up yet. |
| `reconciliation_required` | A delivery needs action. `evidence.outcome` says which: `refused_before_send` means Apostra refused to send the creative, for example because an asset cannot be delivered; `failed` means the Source refused it, never answered, or the delivery ran out of time. |
| `not_applicable` | None of your Sources takes a creative before a buy, so nothing was sent. |
| `unknown` | Apostra cannot say. `evidence.outcome` says why, and what to do next. |

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.

The refusal guard cannot see a booking Apostra never recorded, such as an order
an ad server created before it failed to traffic the line items. Before you
re-send a refused buy, look in the ad server for an existing order or line item
for it, and confirm the cause of the refusal is fixed, because the same payload
is sent again.

A retry sends the payload the buyer originally submitted, with the flight start
and end and the creative assignments refreshed from the buyer's live media buy.
Package budgets stay as approved. If part of the flight has already run, the
buy keeps its full original budget over fewer remaining days, so confirm the
pacing with the buyer first. If the flight has ended, the forward fails with
`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](https://docs.apostra.com/v2/setup/v3/seller-workflows.md)
* [Goal-seeking campaigns](https://docs.apostra.com/v2/concepts/goal-seeking-campaigns.md), for how the buyer's goal and your commitment are recorded
* [Diagnosing stuck media buys](https://docs.apostra.com/v2/guides/diagnosing-stuck-media-buys.md)
* [Source diagnostics Page](https://docs.apostra.com/v3/seller-source-diagnostics-page.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.