Storefront API Reference

Overview

The Scope3 Storefront API provides capabilities for publishers and technology partners to set up and manage storefronts, configure inventory sources, register agents, and handle billing through both REST and MCP (Model Context Protocol) interfaces.

Connection Methods

REST API
MCP (AI Agents)

REST API (Recommended for traditional integrations)

Standard HTTP methods with JSON request/response bodies.Production:

https://api.interchange.io/api/v2/storefront

Example:

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

Canonical Storefront Agent URL

Publishers should list this URL in adagents.json for the managed Interchange storefront agent.Production:

https://interchange.io

OpenAPI Specification

Download the OpenAPI specification for SDK generation or API exploration:

Production: /api/v2/storefront/openapi.yaml

Authentication

All API requests require authentication using your Scope3 API key:

Authorization: Bearer scope3_your_api_key_here

Get API Key

Request API credentials to get started

Storefront Capabilities

The Storefront API provides access to:

Storefronts — Create, view, update, and delete storefronts
Inventory Sources — Manage inventory sources and register agents within storefronts
Reporting — Delivery metrics for every media buy your Merchandising Agent is a party to through your Storefront inventory sources (advertiser → media buy → package)
Billing — Stripe Connect provisioning, account status, transactions, and payouts

REST API Endpoints

Storefronts

Manage storefronts for your publisher integration. Each customer has exactly one storefront, which is automatically created in PENDING when the seller signs up — POST /api/v2/storefront is idempotent and returns the existing storefront if one is already provisioned. There is no delete endpoint; storefronts are activated or disabled via PUT.

Method	Endpoint	Description
GET	`/api/v2/storefront`	Get your storefront
PUT	`/api/v2/storefront`	Update storefront (also used to activate / disable)
POST	`/api/v2/storefront`	Idempotent: returns the existing storefront, creates one if missing
GET	`/api/v2/storefront/readiness`	Check if storefront is ready to go live
GET	`/api/v2/storefront/readiness/compliance`	Deep AdCP compliance probe of registered agents

Example — Configure Storefront:

curl -X PUT https://api.interchange.io/api/v2/storefront \
  -H "Authorization: Bearer scope3_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Media Network",
    "publisherDomain": "acme.com",
    "operatorDomain": "acme.com",
    "brandName": "Acme",
    "logoUrl": "https://acme.com/logo.svg"
  }'

Example — Check Readiness:

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

Inventory Sources

Manage inventory sources within a storefront. To register an agent, create an inventory source with executionType: "agent" and provide the agent’s endpoint URL and protocol.

Method	Endpoint	Description
GET	`/api/v2/storefront/inventory-sources`	List inventory sources
POST	`/api/v2/storefront/inventory-sources`	Create inventory source
GET	`/api/v2/storefront/inventory-sources/:sourceId`	Get inventory source
PUT	`/api/v2/storefront/inventory-sources/:sourceId`	Update inventory source
DELETE	`/api/v2/storefront/inventory-sources/:sourceId`	Delete inventory source
GET	`/api/v2/storefront/inventory-sources/:sourceId/modular`	Inspect modular source setup state
PATCH	`/api/v2/storefront/inventory-sources/:sourceId/modular/modules/:moduleInstanceId/config`	Update non-secret modular source module configuration

Modular inventory sources (executionType: "MODULAR_SOURCE") are composed from source-side modules such as inventory feeds, booking ledgers, trafficking integrations, status sync, reporting imports, and human-in-the-loop work queues. Use the modular projection endpoint to inspect module contracts, lifecycle stages, automated/HITL/unsupported modes, missing setup fields, and open source work items. The projection reports setup-state and configuration completeness; it does not guarantee that runtime media-buy inputs, upstream booking, trafficking, or human review are complete. The module config endpoint writes non-secret module configuration only. It can set manual module states such as CONFIGURING, DISABLED, or ERROR, but it cannot set ACTIVE; active execution state is derived by the execution workflow. Example — Register an Agent as an Inventory Source:

curl -X POST https://api.interchange.io/api/v2/storefront/inventory-sources \
  -H "Authorization: Bearer scope3_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceId": "retail-network-agent",
    "name": "Retail Network Agent",
    "executionType": "agent",
    "type": "SALES",
    "endpointUrl": "https://my-agent.example.com/mcp",
    "protocol": "MCP",
    "authenticationType": "API_KEY"
  }'

Reporting

Delivery reporting for every media buy your Merchandising Agent is a party to through your Storefront inventory sources. The Storefront customer does not own the underlying media buys — these are buyer-side campaigns flowing through your inventory sources — but you have visibility because your Merchandising Agent participates in each transaction. Hierarchy: advertiser → media buy → package (no campaign level).

Method	Endpoint	Description
GET	`/api/v2/storefront/reporting/metrics`	Hierarchical or time-series reporting metrics

Query parameters:

view — summary (default, hierarchical) or timeseries (flat per-day rows)
startDate / endDate — ISO YYYY-MM-DD. Falls back to the trailing days window.
days — Trailing window length (default 7, max 90, 0 for the full storefront timeframe)
inventorySourceId — Limit to media buys flowing through a single inventory source
download — When true, returns a signed CSV download URL instead of JSON
demo — When true, returns synthetic data (useful before live media buys exist)

Example — Last 7 days, summary view:

curl https://api.interchange.io/api/v2/storefront/reporting/metrics \
  -H "Authorization: Bearer scope3_your_api_key_here"

Example — Time-series for one inventory source:

curl "https://api.interchange.io/api/v2/storefront/reporting/metrics?view=timeseries&days=30&inventorySourceId=retail-network-agent" \
  -H "Authorization: Bearer scope3_your_api_key_here"

Example — CSV export:

curl "https://api.interchange.io/api/v2/storefront/reporting/metrics?download=true&days=30" \
  -H "Authorization: Bearer scope3_your_api_key_here"

Storefront Billing

Stripe Connect billing integration for storefronts.

Method	Endpoint	Description
POST	`/api/v2/storefront/billing/connect`	Provision Stripe Connect account
GET	`/api/v2/storefront/billing`	Get billing configuration
GET	`/api/v2/storefront/billing/status`	Get Stripe account verification status and balance
GET	`/api/v2/storefront/billing/transactions`	List balance transactions (cursor-paginated)
GET	`/api/v2/storefront/billing/payouts`	List payouts (cursor-paginated)
GET	`/api/v2/storefront/billing/onboard`	Get a fresh Stripe onboarding URL

Query Parameters for transactions and payouts:

limit — Maximum results per page (1–100, default 25)
starting_after — Cursor for pagination (ID of last item from previous page)

Example — Provision Stripe Connect:

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

Example — List Transactions:

curl "https://api.interchange.io/api/v2/storefront/billing/transactions?limit=25" \
  -H "Authorization: Bearer scope3_your_api_key_here"

MCP Tools

The Storefront MCP server uses a generic tool pattern. AI agents interact with the full REST API surface through these tools:

Tool	Description
`ask_about_capability`	Query the API documentation to look up correct endpoint paths, field names, and request schemas. Call this before `api_call` when unsure of the exact interface.
`api_call`	Authenticated HTTP proxy to any storefront REST endpoint. Supports all methods (GET, POST, PUT, PATCH, DELETE) with full request/response passthrough.
`health`	Health check to verify the API is reachable.

Required workflow for AI agents: Always call ask_about_capability first to retrieve accurate field names and schemas before calling api_call. Field names are camelCase (e.g. agentId, not agent_id).

Supported Endpoint Families

The api_call tool allows access to:

Endpoint Family	Example Operations
`/api/v2/storefront`	Storefront CRUD, readiness checks
`/api/v2/storefront/inventory-sources/*`	Inventory source and agent management
`/api/v2/storefront/billing/*`	Stripe Connect provisioning, transactions, payouts

Response Format

All responses follow a consistent structure:

{
  "data": { ... },
  "error": null,
  "meta": {
    "requestId": "req_abc123",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

Error Response:

{
  "data": null,
  "error": {
    "code": "NOT_FOUND",
    "message": "Agent not found"
  },
  "meta": {
    "requestId": "req_abc123",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

Support

For technical support, contact us at support@scope3.com.

​Storefront API Reference

​Overview

​Connection Methods

​REST API (Recommended for traditional integrations)

​Canonical Storefront Agent URL

​OpenAPI Specification

​Authentication

Get API Key

​Storefront Capabilities

​REST API Endpoints

​Storefronts

​Inventory Sources

​Reporting

​Storefront Billing

​MCP Tools

​Supported Endpoint Families

​Response Format

​Support

Storefront API Reference

Overview

Connection Methods

REST API (Recommended for traditional integrations)

Canonical Storefront Agent URL

OpenAPI Specification

Authentication

Storefront Capabilities

REST API Endpoints

Storefronts

Inventory Sources

Reporting

Storefront Billing

MCP Tools

Supported Endpoint Families

Response Format

Support