Storefront Onboarding

The v2 API is in active development. The onboarding flow described here may evolve before general availability.

Overview

A storefront is the seller-side surface in the Scope3 marketplace. It represents your brand, the inventory sources you offer through agentic protocols, and the billing relationship that lets buyer agents transact with you. The seller journey has four user-visible steps, mirroring the in-app onboarding UI:

Verify your company — resolve your brand from the AAO registry, set your operator domain, and auto-verify (or fall back to manual KYC).
Connect an agent — register an inventory source backed by an ADCP-compatible agent from the AAO registry. Storefronts are limited to one agent today.
Set up billing (optional by default) — connect Stripe to let Scope3 clear payments. Becomes required once a connected agent advertises agent billing (accounts.supported_billing contains "agent") — buyers can ask Scope3 to clear in that case, so Stripe Connect is needed. If you skip this step on an optional storefront, your sales agent operates on external agreements with buyers only — Scope3 will not clear payments and you must bill the buyer directly.
Go live — confirm readiness and flip the storefront to ACTIVE.

A few helper endpoints support these steps but are not standalone “steps”:

POST /resolve-brand — looks up your brand in the AAO registry. Used inside Step 1 to pre-fill the form.
GET /discover-agents — surfaces agents AAO knows about for your domain. Used inside Step 2.
GET /readiness — a status query you can call any time to see what gates remain. Surfaced in Step 4 (and re-run server-side at activation).

Each customer has one storefront, and each storefront connects one agent today. There is no customerId path parameter — the storefront is resolved from your API key’s customer context.

Who this is for

Publishers and sales houses connecting their inventory to agentic buyers
Retail media networks exposing on-site or off-site inventory through ADCP-compatible agents
Any seller who wants buyer agents (e.g. Scope3, Claude, custom buyers) to be able to discover and transact against their inventory

Prerequisites

Scope3 API key

Generate a key at interchange.io/user-api-keys. Keys start with scope3_ and authorize all storefront endpoints.

A registered brand on AAO

Your brand should have a brand.json published and resolvable through the AAO registry at agenticadvertising.org. If you don’t have one yet, the resolve-brand call returns a builderUrl that points you to the registry’s brand builder.

At least one ADCP-compatible agent

A SALES, SIGNAL, CREATIVE, or OUTCOME agent reachable over MCP or A2A. You’ll need its endpoint URL, protocol, and (for non-OAuth agents) auth credentials.

Optional: Stripe account

Required only if you want Scope3 to settle payments through your storefront. Stripe Connect provisioning is gated to non-child customer accounts.

Onboarding flow

Verify your company

The first thing a seller does is identify their company so Scope3 can pull their brand profile from AAO and validate the operator domain. This step combines a brand lookup, a storefront update, and an automatic operator-domain verification check.

1. Resolve your brand (helper)

Look up your brand in the AAO registry to grab the canonical brand name and logo URL. This call has no side effects — it’s only used to populate the storefront update payload.

curl -X POST https://api.interchange.io/api/v2/storefront/resolve-brand \
  -H "Authorization: Bearer scope3_..." \
  -H "Content-Type: application/json" \
  -d '{ "domain": "acme.com" }'

Response (resolved)

{
  "resolved": true,
  "domain": "acme.com",
  "brandName": "Acme",
  "logoUrl": "https://cdn.example.com/acme-logo.svg",
  "manifestUrl": "https://acme.com/.well-known/brand.json",
  "manifest": { "...": "full brand.json" },
  "registryEntry": { "...": "AAO registry entry" },
  "authorizedOperators": [
    { "domain": "acme-media.com", "scope": "primary" }
  ],
  "houseBrand": false
}

If no manifest is found, the call returns 200 with { "resolved": false, "builderUrl": "https://agenticadvertising.org/brand" } — point the operator at the builder URL to publish a brand.json.

The domain field is validated against a strict FQDN regex. IP addresses and internal hostnames are rejected to prevent SSRF.

2. Write the brand fields onto your storefront

If your customer doesn’t yet have a storefront record, create one first:

curl -X POST https://api.interchange.io/api/v2/storefront \
  -H "Authorization: Bearer scope3_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Media",
    "publisherDomain": "acme.com",
    "plan": "basic"
  }'

POST /storefront is idempotent — if a storefront already exists for your customer, the existing record is returned instead of creating a duplicate.Then update it with the brand fields from resolve-brand plus your operator domain:

curl -X PUT https://api.interchange.io/api/v2/storefront \
  -H "Authorization: Bearer scope3_..." \
  -H "Content-Type: application/json" \
  -d '{
    "operatorDomain": "scope3.com",
    "brandName": "Acme",
    "logoUrl": "https://cdn.example.com/acme-logo.svg"
  }'

Response

{
  "platformId": "acme-media",
  "name": "Acme Media",
  "publisherDomain": "acme.com",
  "operatorDomain": "scope3.com",
  "brandName": "Acme",
  "logoUrl": "https://cdn.example.com/acme-logo.svg",
  "operatorDomainVerified": true,
  "plan": "basic",
  "status": "PENDING",
  "createdAt": "2026-04-25T12:00:00.000Z",
  "updatedAt": "2026-04-25T12:00:00.000Z"
}

When you set operatorDomain, the API automatically compares it against your customer’s registered customerDomain (and your parent customer’s, if applicable). If they match, operatorDomainVerified flips to true immediately. Otherwise a verification request is sent to Scope3 staff and you’ll need a manual KYC review.The flag is recomputed only when the operator domain actually changes — manual superadmin verifications are preserved across unrelated edits.

Updatable fields on PUT /storefront: name, publisherDomain, plan, status, operatorDomain, brandName, logoUrl. At least one field must be provided.

Connect an agent (inventory source)

An inventory source binds a named slot inside your storefront to an ADCP-compatible agent. Buyer-side discovery surfaces sources, and media buys flow through the agent attached to each one. Storefronts can connect one agent today — multi-agent storefronts are on the roadmap.

1. Discover agents (helper)

Optional but recommended: see what AAO already knows about your domain. This proxies AAO’s operator and publisher endpoints plus your .well-known/adagents.json.

curl "https://api.interchange.io/api/v2/storefront/discover-agents?domain=acme.com" \
  -H "Authorization: Bearer scope3_..." \
  -H "x-aao-api-key: aao_..."

The x-aao-api-key header is optional. Without it you only get the public registry view. Pass it to also surface storyboard compliance status for agents you operate.

Response

{
  "domain": "acme.com",
  "operator": {
    "domain": "acme.com",
    "member": { "slug": "acme-media", "display_name": "Acme Media" },
    "agents": [
      {
        "url": "https://agent.acme-media.com/mcp",
        "name": "Acme Media Sales",
        "type": "SALES",
        "compliance": {
          "status": "passing",
          "storyboards_passing": 12,
          "storyboards_total": 12,
          "headline": "All scenarios pass"
        }
      }
    ]
  },
  "publisher": {
    "domain": "acme.com",
    "adagents_valid": true,
    "properties": [ { "id": "acme-app", "type": "mobile_app", "name": "Acme App" } ],
    "authorized_agents": [
      { "url": "https://agent.acme-media.com/mcp", "authorized_for": ["display"] }
    ]
  }
}

Responses are cached server-side for 2 minutes per (domain, key fingerprint). Pass &refresh=true to force a re-fetch.

2. Register an inventory source

curl -X POST https://api.interchange.io/api/v2/storefront/inventory-sources \
  -H "Authorization: Bearer scope3_..." \
  -H "Content-Type: application/json" \
  -d '{
    "sourceId": "acme-sales",
    "name": "Acme Media Sales",
    "executionType": "agent",
    "type": "SALES",
    "endpointUrl": "https://agent.acme-media.com/mcp",
    "protocol": "MCP",
    "authenticationType": "API_KEY",
    "auth": { "type": "bearer", "token": "agent_abc123..." },
    "description": "Primary sales agent for Acme on-site display + CTV"
  }'

Required when executionType: "agent": type, endpointUrl, protocol, authenticationType. auth is required for API_KEY and JWT agents and must be omitted for OAUTH and NO_AUTH.

Inventory-source credentials (API keys and JWT private keys) are stored in Google Secret Manager and only referenced by an opaque auth_secret_ref in the database. They are never echoed back in API responses (the response surfaces authConfigured: true instead). Never log, screenshot, or commit raw credentials to source control. Rotate immediately if a credential is exposed.

API_KEY
OAUTH
JWT
NO_AUTH

{
  "authenticationType": "API_KEY",
  "auth": { "type": "bearer", "token": "agent_abc123..." }
}

Token formats bearer, apikey, and api_key are all accepted. The token is stored in Google Secret Manager and never echoed back. The source goes to pending and auto-activates once the agent is reachable with the credential.

{ "authenticationType": "OAUTH" }

Omit the auth field entirely. The response includes an oauth.authorizationUrl you must redirect the operator to. Auth completes out-of-band; the source flips to active once the OAuth callback succeeds.

The OAuth state parameter Scope3 attaches to the authorization URL is opaque, single-use, and carries CSRF entropy bound to your customer + source. Do not decode, modify, or replay it — the callback handler validates state server-side and rejects mismatches. If you proxy the redirect through your own server, forward state byte-for-byte.

{
  "authenticationType": "JWT",
  "auth": {
    "type": "jwt",
    "privateKey": "-----BEGIN PRIVATE KEY-----\n...",
    "issuer": "https://acme.com",
    "subject": "acme-sales",
    "keyId": "key-1",
    "scope": "agent:invoke",
    "tokenEndpointUrl": "https://auth.acme.com/oauth/token",
    "audienceUrl": "https://agent.acme-media.com/mcp"
  }
}

JWT private keys are long-lived signing credentials. Treat them like passwords — never log them, never commit them to source control, and rotate immediately if exposed. Submitted material is stored encrypted in Google Secret Manager and never echoed back.

{ "authenticationType": "NO_AUTH" }

Public agents only. The source is created with status active immediately.

Response

{
  "sourceId": "acme-sales",
  "name": "Acme Media Sales",
  "executionType": "agent",
  "executionConfig": null,
  "status": "pending",
  "agentId": "agent_01HX...",
  "type": "SALES",
  "endpointUrl": "https://agent.acme-media.com/mcp",
  "protocol": "MCP",
  "authenticationType": "API_KEY",
  "authConfigured": true,
  "createdAt": "2026-04-25T12:05:00.000Z",
  "updatedAt": "2026-04-25T12:05:00.000Z"
}

Compliance is checked at connect time and again at activation. Connect-time only requires that the agent is registered with AAO; failing or pending agents can still be connected.

AAO status	Connect a source	Set storefront `ACTIVE`
`passing`	OK	OK
`pending`	OK (logged)	Blocked until it flips to `passing`
`not-passing`	OK (logged)	Blocked until the agent passes
`not-registered`	Rejected with `VALIDATION_ERROR`	n/a
AAO unreachable	Rejected with `SERVICE_UNAVAILABLE` — retry once it recovers	n/a

The activation gate is enforced by the agent_status / agent_connectivity readiness checks (see Step 4) — non-passing agents leave the storefront in a blocked state until compliance flips. The connect-time AAO registry gate runs uniformly for every caller — there is no SuperAdmin bypass.

Storefronts can only connect one agent today (the basic plan limit applies to every storefront). Trying to create a second inventory source returns VALIDATION_ERROR with the message Storefronts can only connect single agent. Remove the existing agent before connecting another. — DELETE /api/v2/storefront/inventory-sources/:sourceId first if you need to swap.

Updates are partial — PUT /api/v2/storefront/inventory-sources/:sourceId accepts any subset of name, description, endpointUrl, protocol, authenticationType, auth, executionConfig, status. Updating auth rotates the stored credential; omitting it preserves the existing one.

Sources can’t be deleted while their backing agent has non-terminal media buys (ACTIVE, PAUSED, PENDING_APPROVAL, or INPUT_REQUIRED). Cancel or terminate those first.

Set up billing (conditional)

Stripe Connect lets Scope3 settle payments on your behalf. Whether billing is required depends on your connected agents’ capabilities:

Optional when no connected agent advertises agent billing. Your storefront can go live without Stripe Connect, but your sales agent is limited to external agreements with buyers (see warning below).
Required when at least one connected agent advertises agent in accounts.supported_billing. Buyers can ask Scope3 to clear payments through that agent, so Stripe Connect must be configured before activation. The readiness check billing_setup returns isBlocker: true until onboarding completes.

If billing is optional and you skip it, your sales agent will be limited to external agreements with buyers. Scope3 will not support payment clearing for inventory sold through this storefront, and the seller is responsible for billing the buyer directly.

Child customer accounts always inherit billing from the parent and cannot provision their own.

1. Provision a Connect account

curl -X POST https://api.interchange.io/api/v2/storefront/billing/connect \
  -H "Authorization: Bearer scope3_..."

Response

{
  "stripeConnectedAccountId": "acct_1Abc...",
  "onboardingUrl": "https://connect.stripe.com/setup/e/acct_1Abc.../..."
}

Redirect the operator to onboardingUrl to complete Stripe’s KYC flow.

2. Re-fetch onboarding link

If the operator drops out mid-onboarding, get a fresh link:

curl https://api.interchange.io/api/v2/storefront/billing/onboard \
  -H "Authorization: Bearer scope3_..."

3. Check status + balance

curl https://api.interchange.io/api/v2/storefront/billing/status \
  -H "Authorization: Bearer scope3_..."

Response

{
  "accountId": "acct_1Abc...",
  "chargesEnabled": true,
  "payoutsEnabled": true,
  "requirements": {
    "currentlyDue": [],
    "eventuallyDue": ["external_account"]
  },
  "balance": {
    "available": [{ "amount": 4250000, "currency": "usd" }],
    "pending": [{ "amount": 120000, "currency": "usd" }]
  }
}

Other billing endpoints

Endpoint	Purpose
`GET /api/v2/storefront/billing`	Current platform fee %, additional fees, currency, net days
`PUT /api/v2/storefront/billing`	Admin-only — update fee config
`GET /api/v2/storefront/billing/transactions`	Cursor-paginated balance transactions
`GET /api/v2/storefront/billing/payouts`	Cursor-paginated payouts
`POST /api/v2/storefront/billing/account-session`	Embedded Stripe Connect session for in-app onboarding UI
`GET /api/v2/storefront/billing/accounts`	Parent customers — billing status across child accounts

Parent customers can pass ?targetCustomerId=<childId> on every /api/v2/storefront/billing/* endpoint to operate on a child’s billing. Access is validated against the parent/child relationship before each call.

Go live

Activation flips the storefront from PENDING to ACTIVE. Buyer agents can only discover and transact against your inventory once you’re live.

1. Confirm readiness

GET /api/v2/storefront/readiness runs every gate that activation will check server-side. Call it any time during onboarding to see what’s still missing.

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

Response

{
  "platformId": "acme-media",
  "status": "ready",
  "checks": [
    {
      "id": "inventory_sources",
      "name": "Inventory sources",
      "category": "inventory",
      "description": "At least one source has been configured.",
      "status": "complete",
      "isBlocker": true,
      "method": "agent",
      "details": "1 source configured"
    },
    {
      "id": "agent_status",
      "name": "Agent status",
      "category": "agents",
      "description": "All agents are active.",
      "status": "complete",
      "isBlocker": true,
      "details": "1 of 1 agents are active"
    },
    {
      "id": "agent_auth",
      "name": "Agent authentication",
      "category": "agents",
      "description": "All agents have been authenticated.",
      "status": "complete",
      "isBlocker": true,
      "details": "1 of 1 agents are authenticated"
    },
    {
      "id": "billing_setup",
      "name": "Billing",
      "category": "billing",
      "description": "Stripe Connect onboarding complete.",
      "status": "complete",
      "isBlocker": false,
      "details": "Stripe Connect is complete"
    }
  ]
}

What each check means

inventory_sources (blocker) — at least one source must exist.
agent_status (blocker) — every agent backing a source must be ACTIVE and have AAO compliance status passing. Sources connected with a non-passing agent will keep this check in partial until compliance flips.
agent_auth (blocker) — non-OAuth agents must have a stored credential. OAuth agents are excluded once their token is captured.
agent_connectivity (blocker, only on GET /readiness/compliance) — runs the ADCP comply() test suite against each agent in sandbox mode (60s timeout). Returns per-agent track results and observations.
billing_setup (conditional blocker) — Stripe is optional when no connected agent advertises agent billing in its capabilities; the check returns status: optional/partial with isBlocker: false and the external-agreements warning. Stripe becomes required once any connected agent declares agent in accounts.supported_billing; the check then returns status: missing/partial with isBlocker: true until Stripe onboarding completes. In non-production environments the check short-circuits to optional regardless of Stripe state so dev/staging storefronts can go live without Stripe.

Top-level status is blocked if any check with isBlocker: true is not complete, otherwise ready. A check with status: optional is treated as not required.For a deeper agent connectivity test (full ADCP compliance scenarios in sandbox mode), hit:

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

This may take up to 60 seconds.

2. Activate

curl -X PUT https://api.interchange.io/api/v2/storefront \
  -H "Authorization: Bearer scope3_..." \
  -H "Content-Type: application/json" \
  -d '{ "status": "ACTIVE" }'

The API re-runs readiness server-side before applying the change. If any blocker is still failing, the request is rejected with the failing check descriptions:

Rejection

{
  "error": "VALIDATION_ERROR",
  "message": "Cannot activate storefront: All agents must be active to go live; All agents must be authenticated to go live",
  "field": "status"
}

When activation succeeds, every agent in PENDING status that’s linked through a source is automatically promoted to ACTIVE so buyer traffic can route through it.

Lifecycle states

Status	Meaning
`PENDING`	Created but not live. Buyer-side discovery does not surface it.
`ACTIVE`	Live. Buyer agents can discover the storefront and transact.
`DISABLED`	Temporarily off. Existing media buys remain bound but new ones can’t be placed.

Allowed transitions: PENDING ↔ ACTIVE ↔ DISABLED (you can’t go straight from DISABLED to PENDING).

Troubleshooting

`AAO compliance pending` — agent is in registry but tests are still running

This is logged but not a blocker. The source is created and will auto-activate once the agent is reachable. No action required unless the status flips to not-passing.

`Agent must pass AAO compliance testing` — endpoint returned `not-passing`

Visit agenticadvertising.org and check the storyboard test results for your agent URL. Resolve the failing scenarios in your agent implementation, wait for the next test run, then retry source creation.

`Agent must be registered with AAO to connect`

The agent’s endpointUrl doesn’t appear in the AAO registry at all. Register it through the AAO operator dashboard before retrying.

`Cannot activate storefront: All agents must be active to go live`

Your agent record is PENDING. Most often this means the auth credential hasn’t been verified yet. Re-submit the source with a fresh auth block, or for OAuth agents make sure the OAuth callback completed.

`Cannot activate storefront: All agents must be authenticated to go live`

A non-OAuth agent has no stored credential. PUT /api/v2/storefront/inventory-sources/:sourceId with an auth block to set one.

`agent_connectivity` failed in compliance check

Look at the compliance array on the failing check — each entry has per-track failureReason, summary, and observations. The most common causes are auth misconfiguration, schema drift between your agent and the ADCP spec, and agent-side timeouts beyond 60s.

Storefront says `operatorDomainVerified: false` even though my domain matches

Verification only runs when operatorDomain is being changed. If you set the domain before the customer’s customerDomain was registered, update operatorDomain to the same value again to trigger re-evaluation, or have a Scope3 admin verify manually.

`Stripe is not configured`

Stripe credentials are missing on the API server. Contact Scope3 support — this is environment config, not a customer-side issue.

`Child customers cannot provision billing accounts directly`

Your customer is a child of a parent org. Either provision billing on the parent and inherit, or have the parent call POST /api/v2/storefront/billing/connect?targetCustomerId=<your-id> on your behalf.

Next steps

Storefront API Reference — full endpoint reference for storefront, billing, and inventory source endpoints
Authentication — API key and OAuth flows
Storefront object guide — how buyer agents see your storefront once it’s live (discovery, credentials, sources)

Overview

Setup

Object Guides

Workflows

Connections

Reference

Release Notes

Overview

Who this is for

Prerequisites

Onboarding flow

1. Resolve your brand (helper)

2. Write the brand fields onto your storefront

1. Discover agents (helper)

2. Register an inventory source

1. Provision a Connect account

2. Re-fetch onboarding link

3. Check status + balance

Other billing endpoints

1. Confirm readiness

2. Activate

Lifecycle states

Troubleshooting

Next steps

Overview

Setup

Object Guides

Workflows

Connections

Reference

Release Notes

Documentation Index

​Overview

​Who this is for

​Prerequisites

​Onboarding flow

​1. Resolve your brand (helper)

​2. Write the brand fields onto your storefront

​1. Discover agents (helper)

​2. Register an inventory source

​1. Provision a Connect account

​2. Re-fetch onboarding link

​3. Check status + balance

​Other billing endpoints

​1. Confirm readiness

​2. Activate

​Lifecycle states

​Troubleshooting

​Next steps

Overview

Who this is for

Prerequisites

Onboarding flow

1. Resolve your brand (helper)

2. Write the brand fields onto your storefront

1. Discover agents (helper)

2. Register an inventory source

1. Provision a Connect account

2. Re-fetch onboarding link

3. Check status + balance

Other billing endpoints

1. Confirm readiness

2. Activate

Lifecycle states

Troubleshooting

Next steps