Get readiness

GET /api/v2/storefront/readiness Computes whether your storefront can transact now. Returns blocking checks for inventory sources, agent status, agent auth, and, for Interchange-cleared storefronts, the confirmed settlement currency (currency_confirmed), plus a per-source sourceDiagnostics[] array used by setup surfaces. Poll this while you connect sources to see what is still missing. For Interchange-cleared storefronts, the currency_confirmed check is a blocker and stays missing until you set a primary settlement currency with PUT /api/v2/storefront { "defaultCurrency": "USD" } (ISO-4217). It is independent of billing setup — saving payout details does not satisfy it. There is no implicit currency. A storefront without a supported defaultCurrency is blocked, absent from transaction-ready discovery, and rejects new media buys. Setting a supported currency removes that blocker automatically; it does not rewrite the seller’s pause choice. Direct sales adapter storefronts run by our expert agents skip currency_confirmed and settlement_currency_match because Interchange does not pay the seller on that path; the buyer pays the downstream platform directly through their selected platform account. For Interchange-cleared storefronts that need to be paid in more than one currency, also send paymentCurrencies — the ISO-4217 currencies your storefront will be paid in, e.g. PUT /api/v2/storefront { "defaultCurrency": "USD", "paymentCurrencies": ["USD", "GBP"] }. On a currency you settle there is no FX: the currency a buyer pays in is exactly the currency you are paid in, so you cannot sell a pricing option in a currency that is not in this set. The marketplace may additionally accept a buyer currency outside your set via cross-currency FX — converting each source cost to the buyer’s currency while you are still paid in your own. A media buy must be denominated in a currency you transact (your defaultCurrency is always included); discovery only surfaces a product to a buyer in a currency you accept, and a buyer whose currency you don’t accept gets no products (an empty list, not an error) rather than ones they can’t buy. If paymentCurrencies is empty or omitted, it falls back to defaultCurrency, so a single-currency storefront need not set it. Changing the settlement currency after go-live is guarded. Operator fixed prices are only shown to buyers in the storefront’s settlement currency, so changing defaultCurrency on a live (transacting) storefront can hide products buyers can currently purchase. When the change would hide one or more buyer-visible products, PUT /api/v2/storefront rejects it with a VALIDATION error stating the affected product count; confirm the impact and retry with { "defaultCurrency": "EUR", "confirmCurrencyCatalogImpact": true } to proceed. Hidden products reappear once their fixed prices are re-authored in the new settlement currency. Non-transacting storefronts and zero-impact changes are unaffected.

Request

curl

curl https://api.interchange.io/api/v2/storefront/readiness \
  -H "Authorization: Bearer $SCOPE3_API_KEY"

Response

{
  "platformId": "premium-ctv",
  "status": "blocked",
  "isPaused": false,
  "canTransact": false,
  "effectiveStatus": "blocked",
  "checks": [
    {
      "id": "inventory_sources",
      "name": "Inventory source",
      "description": "Inventory source connected.",
      "category": "inventory",
      "status": "complete",
      "isBlocker": true,
      "method": "agent",
      "details": "1 inventory source connected"
    },
    {
      "id": "agent_auth",
      "name": "Inventory source authentication",
      "description": "Add authentication credentials for your inventory sources.",
      "category": "agents",
      "status": "missing",
      "isBlocker": true
    },
    {
      "id": "currency_confirmed",
      "name": "Currency",
      "description": "Confirm the currency your storefront settles in before going live — it is never chosen for you.",
      "category": "billing",
      "status": "missing",
      "isBlocker": true
    }
  ],
  "sourceDiagnostics": [
    {
      "id": "9007199254740993",
      "sourceId": "src_main",
      "name": "Premium CTV — Direct",
      "executionType": "agent",
      "sourceStatus": "ACTIVE",
      "agentId": "agt_premium_ctv",
      "agentStatus": "ACTIVE",
      "endpointUrl": "https://agent.premium-ctv.example.com/mcp",
      "protocol": "MCP",
      "auth": { "required": true, "configured": false, "type": "api_key" },
      "capabilities": {
        "products": "supported",
        "createMediaBuy": "supported",
        "updateMediaBuy": "unknown",
        "signals": "unsupported",
        "wholesaleProducts": "unknown"
      },
      "productBuilder": {
        "mode": "passthrough",
        "wholesaleProductCount": null,
        "signalCount": null,
        "catalogCacheCold": false,
        "declaredUnsupportedIngredients": false
      },
      "compliance": {
        "passed": false,
        "summary": "1 of 3 tracks failing",
        "checkedAt": "2026-06-06T15:00:00.000Z",
        "trackCounts": { "total": 3, "passing": 2, "partial": 0, "failing": 1 }
      },
      "debug": {
        "version": null,
        "syntheticCapabilities": false,
        "tools": ["get_products", "create_media_buy"],
        "supportedBillings": ["cpm"],
        "channels": ["ctv"],
        "publisherDomains": ["premium-ctv.example.com"],
        "requireOperatorAuth": true
      },
      "lastActivity": null,
      "health": {
        "status": "healthy",
        "lastError": null,
        "lastErrorCode": null,
        "lastErrorAt": null,
        "lastSuccessAt": "2026-06-06T14:59:00.000Z",
        "lastCheckedAt": "2026-06-06T15:00:00.000Z"
      }
    }
  ],
  "setupMode": null,
  "liveness": {
    "state": "setup",
    "reasonCode": "setup_incomplete",
    "reason": "Not live — 2 steps remaining.",
    "remainingSteps": 2,
    "actionPath": null
  }
}

Response fields

Field	Type	Description
`platformId`	string	Your storefront’s public slug
`status`	enum	Overall readiness: `ready` or `blocked`
`isPaused`	boolean	Compatibility-named intake hold. `true` blocks buyer discovery, new buys, and buyer edits without stopping existing delivery; `false` is neutral, not proof that the storefront is live
`canTransact`	boolean	Canonical availability: not paused, not archived, and every current blocker complete
`effectiveStatus`	enum	Derived `archived`, `paused`, `blocked`, or `live`; never stored
`availabilityGuidance`	object	Canonical cause, effect, and fix when a top-level Pause or Archive control blocks buyer-serving work; omitted otherwise
`checks[]`	array	Top-level readiness checks (see below)
`sourceDiagnostics[]`	array	Per-inventory-source diagnostics (see below)
`setupMode`	object \| null	Per-source composition classification and aggregate verdict used by setup surfaces. Fields: `sources[]`, `managedSalesAgents[]`, `composition` (`{ required, sourceCount }`), `passthrough` (`{ sourceCount }`), `unknown` (`{ sourceCount }`), `recommendation` (`"composition"` \| `"passthrough"` \| `"mixed"` \| `"undecided"`). `null` when inference fails (e.g. cold cache).
`liveness`	object	The projected liveness verdict (see below) — one derived status every surface presents the same way

`checks[].guidance`

Every incomplete hard requirement includes one canonical explanation. Murph, V3 account status, and inventory-source reads consume this same object instead of inferring demand or causality from source call counts.

Field	Type	Description
`coverage`	enum	`complete` when the readiness catalog owns the resolution; `missing` makes an unregistered future blocker explicit instead of inventing a fix
`stage`	enum	Currently `before_source_dispatch`: buyer-serving work stops at storefront transaction admission before an inventory source receives `get_products`
`why`	string	Current cause using the check’s live `details` evidence
`effect`	string	Buyer-path consequence, including why source call counts can remain flat while buyers are trying the storefront
`fix`	string	Smallest action that clears the blocker
`subjects[]`	array	Inventory sources directly implicated by the blocker, when known; each row is `{ kind, id, name }`
`evidence`	object	Optional typed evidence. Billing compatibility reports `requiredSupportedBilling` plus each incompatible source’s advertised `supportedBillings` values

Complete hard requirements and non-blocking checks omit guidance.

`liveness`

One derived liveness status per storefront, computed server-side over the checks, source diagnoses, and settlement invariants above. The seller setup page and the account switcher’s per-storefront status dot both present this same verdict — there is exactly one answer to “is my storefront live?”.

Field	Type	Description
`state`	enum	`setup`, `live`, `live_attention`, or `live_critical` (see below)
`reasonCode`	enum	Machine-readable cause: `archived`, `paused_before_live`, `paused_after_live`, `setup_incomplete`, `settlement_ineligible`, `catalog_empty_live`, `go_live_requirement_regressed`, `degraded_source`, `trafficking_error`, or `healthy`
`reason`	string	One human-readable status line, e.g. `"Not live — 2 steps remaining."` or `"Stopped — settlement currency unsupported."`
`remainingSteps`	number \| null	Open go-live blocker count, present only for `state: "setup"`
`actionPath`	string \| null	In-app path of the surface that owns the fix (e.g. `/inventory-sources`). `null` when the fix lives on the home/setup surface

The four states:

setup (rendered gray) — the storefront is not live yet, and that is expected: it is in setup, pre-launch, or deliberately paused before ever going live. Setup is not failure — no matter how many steps remain, a storefront that never went live is never shown as broken.
live (green) — live and healthy. Buyers can discover and buy.
live_attention (yellow) — live, with something worth acting on that has not broken the promise to buyers (for example, a degraded inventory source that isn’t affecting what buyers can purchase).
live_critical (red) — the storefront reached live and the promise to buyers is now broken: it was paused or a go-live requirement regressed after going live (e.g. the settlement currency became unsupported, or the buyable catalog emptied post-launch), or a critical problem is stopping buys.

“Reached live” means durable evidence: a completed real buyer media buy, the recorded setup history showing every current go-live requirement was once complete, or a previously recorded live status. Once your storefront has been observed live it never drops back to setup — a newly introduced or broken requirement shows as live_critical instead, so an outage is always visible (and alerted) as a broken promise, never hidden as setup. A passed no-spend sandbox test alone does not make a storefront “live” — a mid-setup storefront that just ran its first test stays setup. The status reflects the buyer’s reality: a dead source that carries no buyer-visible products does not change the state, and connect/pass-through storefronts (selling through their own third-party sales agent) are never gated on merchandising requirements that don’t apply to their path. A flip away from live sends a proactive notification — you don’t have to notice the dot change color to find out. See Notifications for the storefront.liveness_degraded / storefront.liveness_recovered event types, their payload, and the dedupe rules (a storefront sitting degraded is not re-notified every sweep; a further worsening is).

`checks[]`

Field	Type	Description
`id`, `name`, `description`, `category`	string	Check identity and grouping
`status`	enum	`complete`, `partial`, `missing`, or `optional`. `optional` checks are explicitly skipped (e.g. billing in non-production) and never block
`isBlocker`	boolean	Whether this check blocks going live
`method`	string	How the check was evaluated. Optional
`details`	string	Human-readable detail. Optional
`compliance[]`	array	Per-agent compliance results (present on `agent_connectivity` checks). Each is `{ agentId, agentUrl, passed, summary, tracks[], observations[] }`. A track’s `status` is `pass`/`fail`/`partial`/`skip`; a `skip` track did not run and is labelled “not run” / “no coverage”. `observations[]` carries advisory `{ category, severity, message }` notes. Compliance is informational and does not block going live.

The operator_domain check distinguishes two setup states. If no operator domain is set, it is missing. If a domain is set but not verified yet, it is partial with details like <domain> is pending verification; go-live is still blocked until the registered organization domain is approved or ownership is confirmed. Transaction admission verifies product availability strictly: These wholesale/component checks apply only when product composition is part of the storefront path. A pure third-party sales-agent pass-through storefront is not required to publish or cache a wholesale catalog in Interchange; its live agent path and transaction validation remain the applicable gates.

Untraffickable catalog. source_products_traffickable blocks the flip when EVERY synced product across your non-managed sources is untraffickable (e.g. hosted video with no duration, or a display format with no width/height) — you would otherwise sell nothing that can actually traffic. It stays a non-blocking warning when only some products are affected; the rest can sell.
Unverified catalog. If product availability can’t yet be confirmed (a cold, not-yet-fetched catalog cache), the flip warms the catalog with a live fetch and rechecks once before deciding. If it is still unconfirmed, products_available blocks with “Catalog not yet verified — retry in a moment” instead of allowing a buy.

product_publisher_domains warns when an active product has no publisher-domain mapping or references a domain the storefront has not declared. It remains non-blocking while older catalogs are backfilled. For every storefront, publisher_domains requires at least one declared domain so buyers know what is being sold. Neither check requires that domain to authorize Interchange. The separate publisher_authorization warning reports adagents.json/AAO authorization progress and never blocks transactions. The operator domain identifies the company running the storefront and is not used as a publisher domain unless the seller declares it as one. The compatibility-named publish_validation check requires one durable successful transaction. A completed seller-owned no-spend sandbox test or a successful live buyer media buy satisfies it permanently. The sandbox path can exercise a pre-live storefront without exposing it to ordinary buyer discovery; it is server-authored, seller-scoped, respects Pause, and cannot bypass another readiness blocker. Failed later tests remain diagnostic evidence but do not erase an earlier successful transaction. The check is scoped to the storefront’s connected source mix, because it exists to prove an unproven transaction path — it never asks you to prove plumbing Scope3 already operates:

Managed-only. If every connected source is your Scope3-managed sales agent (ad server), the check reports complete with “Covered by your managed sales agent” — it counts toward your required steps without asking for a separate test.
Mixed. If you also connect a third-party sales agent (or a modular source whose recipe executes campaigns, such as CitrusAd), the check still applies — that path is unproven — and its description names which source(s) the test still needs to cover.
Third-party only. If none of your connected sources is the Scope3-managed sales agent, the check applies as described above.

In exceptional cases Scope3 may approve a storefront-specific service override for publish_validation. The readiness item remains complete but reports method: service_override and names the approval evidence; it never claims a transaction occurred. The exception does not bypass Pause, publisher-domain declaration, product availability, or any other readiness requirement. If a live storefront’s buyer-visible catalog later empties (for example, manual pricing expiring), you get a proactive notification naming the cause and the fix — see Troubleshoot source problems. Its effective status automatically becomes blocked; isPaused is unchanged. Ad-server-derived pricing has a 60-day freshness ceiling. A product priced from ad-server reporting history stays buyable only while its catalog keeps refreshing; if the sync stops and a cached price goes more than 60 days without a refresh, the product is hidden from buyers rather than quoted on a stale price. When this is the only reason your catalog is hidden, the products_available blocker names the stale ad-server sync as the cause and its fix is checking the ad-server connection — not uploading a pricing feed. A successful sync restores the pricing automatically.

`sourceDiagnostics[]`

Field	Type	Description
`id`, `sourceId`	string \| null	Surrogate id and storefront-scoped source id
`name`	string	Inventory source display name
`executionType`, `sourceStatus`	string	Source type and current source lifecycle status
`agentId`, `agentStatus`, `endpointUrl`, `protocol`	string \| null	Linked agent identity and transport
`auth`	object	`{ required, configured, type }` — whether auth is needed, set, and which type
`capabilities`	object	Support state for `products`, `createMediaBuy`, `updateMediaBuy`, `signals`, `wholesaleProducts` — each `supported`, `unsupported`, or `unknown`
`productBuilder`	object \| null	`{ mode (composition\|passthrough\|unknown), wholesaleProductCount, signalCount, catalogCacheCold, declaredUnsupportedIngredients }`. For component-cache diagnostics, `wholesaleProductCount > 0` means cached raw products are available, `declaredUnsupportedIngredients: true` means the source explicitly does not provide usable cached components, and `catalogCacheCold: true` means readiness cannot classify the source until cache refresh has evidence. Third-party sales-agent sources are checked for component-cache readiness only when product composition is on and the source reports AdCP 3.1+ support; otherwise readiness treats them as pass-through.
`compliance`	object \| null	`{ passed, summary, checkedAt, trackCounts: { total, passing, partial, failing } }`
`debug`	object	Sanitized capability metadata: advertised `tools`, `supportedBillings`, `channels`, `publisherDomains`, `version`, `syntheticCapabilities`, `requireOperatorAuth`
`lastActivity`	object \| null	Latest setup activity `{ action, resourceType, resourceId, resourceName, description, timestamp }`
`health`	object	`{ status (healthy\|degraded\|unhealthy\|unknown), lastError, lastErrorCode, lastErrorAt, lastSuccessAt, lastCheckedAt }`

Errors

401 UNAUTHORIZED — missing or invalid bearer token.

See Errors for the full error contract.

Storefront overview

Readiness, marketplace review, and AAO signals.

Inventory sources

Connect the sources readiness checks against.

Diagnose third-party sales agents

Interpret source health and recent ADCP activity.

Discover agents

Inspect the AAO registry for your operator domain.

Getting Started

Operating Your Storefront

Inventory Sources

Real-Time Targeting (TMP)

Approvals & Reviews

Buyer Onboarding

Demand & Signals

Proposals & Agents

Buyer Routing

Analytics & Activity

Billing

Account

Request

Response

Response fields

`checks[].guidance`

`liveness`

`checks[]`

`sourceDiagnostics[]`

Errors

Storefront overview

Inventory sources

Diagnose third-party sales agents

Discover agents

​Request

​Response

​Response fields

​checks[].guidance

​liveness

​checks[]

​sourceDiagnostics[]

​Errors

​Related

Storefront overview

Inventory sources

Diagnose third-party sales agents

Discover agents

Request

Response

Response fields

`checks[].guidance`

`liveness`

`checks[]`

`sourceDiagnostics[]`

Errors

Related