Reading your seller's operating state and plan

A seller account can read two groups of facts about itself without a second call to the status tool: what state it is in right now, and what its plan includes. Both are opt-in. A get of the seller that names neither returns exactly what it returned before.

Read them

Call get with kind: "seller", no id, and either or both of include: ["operating"] and include: ["entitlements"]:

{
  "operating": {
    "status": "live",
    "isPaused": false,
    "archivedAt": null,
    "routingMode": "CHEF"
  },
  "entitlements": {
    "merchandising": true,
    "listingDistribution": false,
    "operatingMode": "AGENTIC_MEDIA_COMPANY"
  }
}

Both includes belong to the seller account that is reading itself. They are refused on any other kind, on a seller read that names an id, and for a buyer account.

Operating state

Field	Meaning
`status`	Whether buyers can use the seller now: `live`, `paused`, `blocked` or `archived`. It is the same value the status tool reports as `state` for a seller account, from the same check.
`isPaused`	`true` while buyer intake is on hold. A hold stops discovery, new buys and buyer edits. It does not pause delivery of buys that already exist. `false` does not by itself make the seller live.
`archivedAt`	When the seller was archived, or `null` if it is not archived. An archived seller is read-only.
`routingMode`	Where buyer requests are routed: `CHEF` for the seller’s Merchandising Agent, or `ADAPTER` for an expert-run adapter implementation.

status is decided in this order, so the first match wins:

archived when the seller is archived.
paused when buyer intake is on hold.
blocked when it is not paused or archived but a requirement for going live is still open. The status tool lists the open requirements as blockers.
live when none of the above applies.

isPaused and archivedAt are the stored values behind status. They are shown beside it so you can see why the seller is paused or archived. blocked has no stored field of its own: it means a setup requirement is open. This is not the same answer as the go-live state or the setup progress in the readiness read. status says whether buyers can use the seller now.

Entitlements

Field	Meaning
`merchandising`	`true` when the seller account is entitled to Merchandising: its plan includes it, or the account holds a separate Merchandising grant. It is a commercial fact. It does not mean a connected source is ready to supply products.
`listingDistribution`	`true` when the seller account is entitled to Listing + Distribution. It is independent of `merchandising`.
`operatingMode`	The seller product the plan provides: `LISTING_ONLY` or `AGENTIC_MEDIA_COMPANY`. It follows the plan only.

save_account accepts an operatingMode too. That is the stored choice the seller made. It does not decide what the seller can do, and entitlements.operatingMode does not read it back: this field is what the plan provides. merchandising and operatingMode are two answers from two checks, and you should not infer one from the other. An account whose plan is a listing but which holds a separate Merchandising grant reads merchandising: true with operatingMode: "LISTING_ONLY".

When a read fails

There is no “unknown” value. If Apostra cannot work out operating or entitlements, for example because a plan lookup timed out, the call fails with SERVICE_UNAVAILABLE and returns neither field, so you never act on a guess. Retry the same call.

Sellers on the V3 tool surface lists every get kind and include a seller account reads.
Reading your agent’s webhook results shows another opt-in include read on get.

Start here

Buy media

Sell media

Help and updates

Reading your seller's operating state and plan

Read them

Operating state

Entitlements

When a read fails

​Read them

​Operating state

​Entitlements

​When a read fails

​Related

Read them

Operating state

Entitlements

When a read fails

Related