Diagnosing a stuck media buy

“Why isn’t my buy live?” should take one call to answer. Every media buy carries fields that say what it’s waiting on, whose side owns a failure, the seller’s own words when there are any, and a reference both sides can quote.

I’m a buyer: why isn’t my buy live?

One-call lookup

GET /api/v2/buyer/media-buys/{mediaBuyId} returns one media buy with every field below. Over MCP, call get with kind: "media_buy" and the id.

curl https://api.semicola.com/api/v2/buyer/media-buys/mb_4Tq8… \
  -H "Authorization: Bearer $SEMICOLA_API_KEY" \
  -H "X-Account-Id: $ACCOUNT_ID"

For every buy on a campaign at once, GET /api/v2/buyer/campaigns/{id}/media-buy-status returns pendingReason, pendingSince, errorCode, errorOwner and blockers per buy. The campaign workspace shows a short label for each buy, such as “Awaiting seller approval”.

Field	What it tells you
`status`	The buy’s status. See media buy statuses.
`pendingAt`	Who holds a `PENDING_APPROVAL` buy: `storefront` (the seller’s review queue) or `salesagent` (the seller’s own system).
`pendingReason`	What the buy is waiting on (below). An annotation, never a status.
`pendingSince`	When the buy started waiting for the seller.
`errorCode`	Why a buy failed or was rejected (below).
`errorOwner`	Who owns the fix: `buyer_input`, `platform` or `seller`.
`sourceMessage`	The seller’s or reviewer’s own explanation, when they gave one. Read this first on a rejection.
`adcpTaskId`	The seller’s task id while it reviews the buy. Poll it with Tasks.
`forwardedAt`	When the seller’s decision sent the buy on to its inventory source.
`buyerReference`	A reference for this buy that both you and the seller can quote.

`pendingReason`: what it’s waiting on

`pendingReason`	Shown as	Meaning	What to do
(none) on a `DRAFT` buy	Staged · not sent	The buy is in your cart. No seller has seen it.	Launch the campaign when you’re ready.
`dispatching`	Sending to seller	Launch is sending the buy now.	Wait.
`awaiting_seller_approval`	Awaiting seller approval	The seller accepted the buy for review. `pendingAt` says where it sits.	Wait. If it runs long, quote `buyerReference` to the seller.
`retrying`	Seller unreachable · retrying	Sending failed in a way that’s safe to repeat.	Launch the campaign again; only these buys are re-sent.

A buy that’s ACTIVE can still be waiting to start or for creatives: the campaign’s operational status (pending_start, pending_creatives) says which. See the campaign page.

`errorCode`: why it failed

`errorCode`	`errorOwner`	Meaning	What to do
`product_no_longer_available`	`platform`	A product in the buy no longer exists at the seller.	Request proposals again and stage a buy with current products.
`source_rejected`	`seller`	The seller’s system declined the buy.	Read `sourceMessage`, address the reason, stage a new buy.
`storefront_rejected`	`seller`	The seller rejected the buy in review.	Read `sourceMessage` (the reviewer’s note) and adjust.
`source_unavailable`	`seller`	The seller couldn’t be reached. Not a refusal.	Launch again later. Escalate with `buyerReference` if it persists.
`invalid_request`	`buyer_input`	Something in the request needs correcting.	Fix the flagged input and launch again.
`quote_expired`	`platform`	The seller’s quote or proposal expired before the buy went out.	Refresh the proposal and stage a new buy.
`platform_error`	`platform`	A fault on Semicola’s side.	File an ask with `save_ask`, quoting `buyerReference`.

When a launch partly fails, the launch result lists each failed buy with a recovery of transient, correctable or terminal and a retrySafe flag. Launching again re-sends only the buys that are still drafts or marked retrying.

What to quote

Quote buyerReference (and forwardedAt when it’s set) when you contact the seller or the Semicola team about a stuck buy. To reach the Semicola team, ask Semi to file an ask, or call save_ask with type: "support".

Push notifications for buy transitions aren’t available yet. Read the buy, or poll its task, to follow it.

I’m a seller: what needs my attention?

Buys that wait on you sit in your storefront’s approval queue.

Queued buys. open_approvals shows the review queue; decide_media_buy_approval approves or rejects one. See Approvals.
Every buy on the storefront. open_media_buys_page lists them, most urgent first.
A failed forward. When you approved a buy but sending it on to your inventory source failed, retry_forward re-sends it with the same idempotency key, so it can’t double-book.

Tasks

Poll a seller’s review task.

Media buy lifecycle

Every status, and how acceptance works.

Start here

Setup

Buy media

Sell media

Guides

Help

Diagnosing a stuck media buy

I’m a buyer: why isn’t my buy live?

One-call lookup

`pendingReason`: what it’s waiting on

`errorCode`: why it failed

What to quote

I’m a seller: what needs my attention?

Tasks

Media buy lifecycle

​I’m a buyer: why isn’t my buy live?

​One-call lookup

​pendingReason: what it’s waiting on

​errorCode: why it failed

​What to quote

​I’m a seller: what needs my attention?

​Related

Tasks

Media buy lifecycle

I’m a buyer: why isn’t my buy live?

One-call lookup

`pendingReason`: what it’s waiting on

`errorCode`: why it failed

What to quote

I’m a seller: what needs my attention?

Related