> ## Documentation Index
> Fetch the complete documentation index at: https://docs.semicola.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Media buys on your storefront

> Every buy placed on your storefront, most urgent first, with its timeline, delivery and the way to re-send a failed forward.

Every media buy a buyer places on your storefront is listed on the **Media buys** page, most urgent
first. From there you open one buy's timeline to see where it is and whether it's stuck.

Open it in the app, ask Semi "show me the buys on my storefront", or call `open_media_buys_page`
(optional `view`: `media_buys`, `creatives` or `delivery`; optional `accountRelationshipId` to show one
buyer's buys).

## Status

| `status`           | Meaning                                                    | Urgency |
| ------------------ | ---------------------------------------------------------- | ------- |
| `pending_approval` | Waiting for a person's decision in Approvals & operations. | high    |
| `forward_failed`   | Approved, but your inventory source didn't accept it.      | high    |
| `forwarding`       | Being sent to your inventory source.                       | normal  |
| `awaiting_source`  | Sent; your source or ad server is still reviewing it.      | normal  |
| `delivering`       | Live.                                                      | normal  |
| `booked`           | Accepted by your source; not delivering yet.               | low     |
| `rejected`         | Declined.                                                  | low     |
| `canceled`         | Canceled.                                                  | low     |
| `completed`        | Finished.                                                  | low     |

Each row shows the `buyerName`, the `advertiserLabel`, `budget`, `flight`, the `forwardOutcome` and
when it last changed.

## The timeline

`open_page` with `page: "media_buy_timeline"` (or `GET /media-buys/{id}/timeline`) shows one buy's
stages with timestamps: received, screened, decided, forwarded, submitted, source moderation,
accepted, delivering (or forward failed). Each stage is `done`, `current`, `pending` or `failed`,
with a detail where there is one.

The timeline flags a buy as **stuck** when:

* the forward failed (with your source's message);
* it has waited for an operator decision for more than 4 hours ("Waiting for an operator decision past
  the SLA.");
* any other stage has made no progress for more than an hour ("No progress from the source yet.").

`references` carries the buy's idempotency key, request id and AdCP task id, for support.

## Re-send a failed forward

When a forward fails, `retry_forward` (with the media buy id or its approval id) re-sends the approved
buy with the same idempotency key, so it can't double-book. Semi asks you to confirm first. Over REST:
`POST /media-buys/{mediaBuyId}/retry-forward`.

## REST

All paths are under `https://api.semicola.com/api/v2/storefront`.

| Method and path                               | What it does                                             |
| --------------------------------------------- | -------------------------------------------------------- |
| `GET /media-buys`                             | Every buy, most urgent first (filters and paging below). |
| `GET /media-buys/{id}/timeline`               | One buy's stages, stuck state and references.            |
| `GET /media-buys/{id}/reporting`              | Delivery for one buy: daily rows and totals.             |
| `GET /reporting/metrics`                      | Delivery across the storefront.                          |
| `POST /media-buys/{mediaBuyId}/retry-forward` | Re-send a failed forward.                                |

The list accepts `status` and `buyerCustomerId` (one buyer's buys), and pages with `limit` (1–200,
default 25) and `cursor`. The page comes back in `meta.pagination` (`nextCursor`, `hasMore`), like
every cursor list; pass `nextCursor` back as `cursor`. `take` and `skip` work as aliases for
`limit` and an offset; `take` wins over `limit`, and `cursor` wins over `skip`. Each row carries the
buyer's `buyerCustomerId`. Filtering by inventory source or flight dates isn't available over REST.

## Related

* [Approvals & reviews](/sell/approvals)
* [Media buy lifecycle](/concepts/media-buy-lifecycle)
* [Buyers](/sell/sponsored-buyers)