Storefront API Reference

Overview

The Interchange 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"

Storefront management connector

Storefront operators connect AI agents to the authenticated management surface at:

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

This stable alias currently redirects to /mcp/v2/storefront.

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 Interchange 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 — payout bank details, fee configuration, and payment terms

REST API Endpoints

Storefronts

Manage storefronts for your publisher integration. Each account 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. Creating a storefront requires both a name and a publisherDomain (a valid domain such as acme.com). The publisher domain is the identity buyers and partners look your storefront up by — it connects your inventory to buyer demand. Existing storefronts are unaffected; only new create requests must supply it.

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`	Create a storefront (`name` + `publisherDomain` required); idempotent — returns the existing storefront if one exists
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 account 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

Payout bank details and fee configuration for storefronts. Interchange pays sellers by bank transfer using the payout details on file; normal storefronts use Interchange-cleared (agent) settlement today. Seller-cleared settlement is planned but is not yet configurable.

Method	Endpoint	Description
PUT	`/api/v2/storefront/billing/payout-details`	Save the bank account Interchange pays into (account number is write-only)
GET	`/api/v2/storefront/billing`	Get billing configuration and masked payout details
PUT	`/api/v2/storefront/billing`	Update fee configuration (admin)
GET	`/api/v2/storefront/billing/accounts`	Organizations — billing status across their accounts

Example — Set payout details:

curl -X PUT https://api.interchange.io/api/v2/storefront/billing/payout-details \
  -H "Authorization: Bearer scope3_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "beneficiaryName": "Meridian Media Group Inc.",
    "addressLine1": "500 Harbor Blvd",
    "city": "Seattle",
    "region": "WA",
    "postalCode": "98101",
    "countryCode": "US",
    "accountNumber": "000123456789",
    "bankIdentifierType": "FEDWIRE_ABA",
    "bankIdentifierValue": "021000021",
    "currency": "USD"
  }'

Example — Get billing configuration:

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

MCP Tools

The Storefront MCP server exposes dedicated tools for session-level actions and a generic api_call tool for REST operations. Use the dedicated MCP tool when one exists. Use api_call for storefront REST operations that do not have a more specific tool. Every api_call requires a named operation; the legacy raw method + endpoint form is no longer supported and is rejected.

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`	Dispatches a named storefront `operation` (typed request/response). The method and endpoint are derived from the operation; pass `pathParams`, `params`, and `body` as needed. Call `ask_about_capability` to find the right operation.
`customer_switch`	Switch the active account context. Available to any user with membership in more than one account; SuperAdmin users can switch to any account.
`health`	Health check to verify the API is reachable.

Required workflow for AI agents: Choose the most specific MCP tool first. For account context, call customer_switch directly instead of routing through api_call. For REST operations, call ask_about_capability first when unsure of the exact interface, then call api_call with an operation name. Field names are camelCase (e.g. agentId, not agent_id).

Switch Account

Account switching is session state. It is not a per-call REST parameter and is not available through api_call. To operate on a different account in the same MCP session, call the dedicated customer_switch MCP tool:

{
  "tool": "customer_switch",
  "arguments": { "customerId": 123 }
}

After switching, retry the original api_call without customerId in params or body. If the target account is not available to the current MCP session, re-authenticate with that account’s credentials.

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, including modular product, capability, and selector reads; consequential modular writes and credentials remain in trusted Tasks/UI
`/api/v2/storefront/reporting/*`	`get_storefront_reporting_metrics`, `get_storefront_margin_reporting`
`/api/v2/storefront/billing/*`	Payout details, fee configuration, billing status across an organization’s accounts

Use get_current_account and list_accounts to inspect the active account and the account IDs available before calling the dedicated customer_switch tool.

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)

​Storefront management connector

​Canonical Storefront Agent URL

​OpenAPI Specification

​Authentication

Get API Key

​Storefront Capabilities

​REST API Endpoints

​Storefronts

​Inventory Sources

​Reporting

​Storefront Billing

​MCP Tools

​Switch Account

​Supported Endpoint Families

​Response Format

​Support

Storefront API Reference

Overview

Connection Methods

REST API (Recommended for traditional integrations)

Storefront management connector

Canonical Storefront Agent URL

OpenAPI Specification

Authentication

Storefront Capabilities

REST API Endpoints

Storefronts

Inventory Sources

Reporting

Storefront Billing

MCP Tools

Switch Account

Supported Endpoint Families

Response Format

Support