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

# Buyers

> See every buyer account that transacts with your storefront, and approve, suspend or reactivate it.

Every Semicola buyer account that calls your storefront gets a **buyer relationship** with it. The
**Buyers** page ("Buyer accounts working with your storefront.") lists them with what each has done on your inventory, and lets you approve,
suspend or reactivate each one.

Open it in the app, ask Semi "who's buying from us?", or call `open_seller_buyers` (`filter`: `all`
or `awaiting`).

## What each buyer shows

| Field                          | Notes                                                           |
| ------------------------------ | --------------------------------------------------------------- |
| `buyerName`, `buyerCustomerId` | The buyer account.                                              |
| `status`                       | `pending`, `active` or `suspended` (below).                     |
| `posture`                      | `prepay` or `credit`: the billing path you chose for the buyer. |
| `firstSeenAt`                  | When the buyer first called your storefront.                    |
| `mediaBuys`, `activeMediaBuys` | Buys on your storefront, all and live.                          |
| `bookedBudget`                 | Budget booked with you.                                         |
| `creativesSynced`              | Creatives the buyer has sent you.                               |
| `deliveredImpressions`         | Delivery on your inventory, when reported.                      |

The filter switches between **All** and **Awaiting you**, which shows the `pending` buyers.

## Status

| Status      | Meaning                                                               | New media buys? |
| ----------- | --------------------------------------------------------------------- | --------------- |
| `pending`   | The buyer has called your storefront and you haven't reviewed it yet. | Yes             |
| `active`    | You approved it.                                                      | Yes             |
| `suspended` | You paused it.                                                        | No              |

A buyer's first call creates the relationship as `pending`. Pending doesn't block anything: it marks
the buyer for your review. A `suspended` buyer's new media buys are refused with `ACCOUNT_SUSPENDED`
("… has paused media buys from this account. Contact the seller."). Suspending doesn't stop delivery
on buys that are already running, and doesn't block changes to them.

Allowed changes:

* **Approve** `pending → active`, optionally setting the `posture`.
* **Suspend** `pending` or `active → suspended`.
* **Reactivate** `suspended → active`. Reactivating anything else returns `CONFLICT` ("Only a suspended
  buyer can be reactivated."); approving a buyer that isn't pending returns "This buyer is already …".

## MCP and REST

| Action     | MCP                                                     | REST (under `/api/v2/storefront`)                                                   |
| ---------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| List       | `open_seller_buyers`                                    | `GET /buyers?filter=awaiting` (or `GET /sponsored-buyers`)                          |
| Approve    | `approve_sponsored_buyer` (`relationshipId`, `posture`) | `POST /buyers/{relationshipId}` with `{ "action": "approve", "posture": "prepay" }` |
| Suspend    | `suspend_sponsored_buyer` (`relationshipId`)            | `POST /buyers/{relationshipId}` with `{ "action": "suspend" }`                      |
| Reactivate | `reactivate_sponsored_buyer` (`relationshipId`)         | `POST /buyers/{relationshipId}` with `{ "action": "reactivate" }`                   |

The three MCP writes always ask the person to confirm. The REST path
`POST /sponsored-buyers/{buyerCustomerId}/{action}` also works, keyed by the buyer's customer id
instead of the relationship id. Every change is recorded in your storefront
[Activity](/guides/audit-logs).

## Not available yet

Posture is recorded for your records only: Semicola doesn't clear media payments for sellers yet, so
`prepay` and `credit` don't change how money moves. Buyer accounts confined to a single storefront,
and invitations for new buyers, aren't available.

**Buyer account mapping** isn't available either: there's no per-inventory-source coverage view
(`Mapped`, `Not set up`, `Stale`…), no source account roster search, no mapping CSV import or export,
and no `get_seller_accounts` tool. A buyer relationship is one record per buyer account, not per
operator and brand.

## Related

* [Approvals & reviews](/sell/approvals)
* [Demand inbox](/sell/demand-inbox)