Skip to main content
These workflows require an enrolled Seller account. In v3, “Seller Account” is the operator workspace; a Storefront is the buyer-facing selling surface it operates.

​
Begin with readiness

Call get_status before changing configuration. Its blockers explain why work is stopped before a buyer request reaches an inventory source and provide a typed tool or Page for the next action. Do not infer demand from source traffic alone. A Seller Account that is not ready may correctly have no source calls because work stops earlier.

​
Read and configure Seller identity

The Seller Account is a singleton, so read it without an ID:
The projection distinguishes:
  • configuredCapabilities — the declaration you saved; and
  • capabilities — what buyers can use after source topology and approval policy are applied.
These values may disagree. capabilitiesLocked and capabilityDerivation explain why. Send capability patches rather than replacing the whole set:
setupIntent describes how the Seller Account is intended to connect. It does not apply a capability preset or change the capability flags. Declare each supported capability explicitly through capabilities; then read the Seller again to see the effective values derived from source topology and policy. Changing operatorDomain may invalidate profile fields curated for the old identity. If populated fields would be cleared, the tool refuses the write and requires confirmOperatorDomainProfileReset: true after you review the impact.

​
Add and diagnose inventory

Use save_inventory_source for typed source configuration. Credentials and OAuth grants stay in the relevant Page rather than model-visible arguments. Read a source with connection and diagnostic evidence:
Connection and health answer different questions: usable credentials can exist while every call fails. Diagnostics follow the source’s actual connection. If the source has no supported diagnostic marker, the include is reported as unsupported instead of guessing another source or agent ID. Common Pages include:
  • connect_ad_server for credentials and OAuth;
  • ad_server_source for connection management;
  • ad_server_diagnostics for sync and refresh history; and
  • source_diagnostics for call-level investigation.

​
Manage publisher coverage

Coverage separates declarations from evidence:
  • declared domains and properties are operator claims;
  • discovered properties remain evidence from publisher sources; and
  • authorization is a verdict derived from the current roster and proof.
Read coverage with:
Use save_coverage to add or remove one domain or property without rebuilding the entire roster. Domain declarations in one call are applied before property claims beneath them, so a new domain and property may be declared together. Removing publisher-origin evidence is refused; retract only claims you own.

​
Operate work items and approvals

search({ "kind": "work_item" }) is the unified queue for work waiting on the Seller Account. The returned workItemKind determines its state vocabulary and the fields required by save_work_item. Saving the same completed result again returns unchanged. A conflicting correction is refused rather than overwriting authoritative evidence. AI evaluation, reassignment, and forwarding retry remain Page actions. They cost money, move accountability, or repeat an external side effect, so they are not fields on a declarative save.

​
Read seller-side media buys

List every buy that landed in the Seller Account:
Filter by sourceId, seller status, buyer customer ID, or ISO 8601 flight-start instants. Pass the opaque nextCursor back unchanged while hasMore is true. Partial source coverage and stale status are reported explicitly. Read one media buy to receive its Seller-scoped exchange timeline, approval, source legs, identifiers, and newest failure. Recovery classes distinguish a transient failure from a correctable or structural one. Add include: ["diagnostics"] for the supporting observation trail.

​
Query delivery and margin

get_delivery supports two reports:
  • delivery — seller-reported delivery over an inclusive range of at most 90 days; and
  • margin — the cumulative seller spread ledger.
Delivery is seller-reported, not buyer-side measurement. Finality does not by itself make a result eligible for billing. Missing source values remain unavailable rather than being invented as zero. Reporting pages are live per call; a cursor anchors continuation but does not create snapshot isolation.

​
Test through a Buyer account

The target v3 model tests selling by switching to a related Buyer account, using a sandbox advertiser, and running the ordinary Buyer workflow. The full vertical is still being completed; use the v2 test-campaign endpoints when that path cannot express the required test yet.