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

Staging:

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

Example:

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

MCP (Model Context Protocol) for AI Agents

JSON-RPC 2.0 over HTTP POST with session management.Production:

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

Staging:

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

Example:

curl -X POST https://api.interchange.io/mcp/storefront \
  -H "Authorization: Bearer scope3_your_api_key_here" \
  -H "Content-Type: application/json" \
  -H "mcp-session-id: your-uuid" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

OpenAPI Specification

Download the OpenAPI specification for SDK generation or API exploration:

Production: /api/v2/storefront/openapi.yaml
Staging: /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
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

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": "snap-ads-agent",
    "name": "Snap Ads Agent",
    "executionType": "agent",
    "type": "SALES",
    "endpointUrl": "https://my-agent.example.com/mcp",
    "protocol": "MCP",
    "authenticationType": "API_KEY"
  }'

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

Documentation Index

​Storefront API Reference

​Overview

​Connection Methods

​REST API (Recommended for traditional integrations)

​MCP (Model Context Protocol) for AI Agents

​OpenAPI Specification

​Authentication

Get API Key

​Storefront Capabilities

​REST API Endpoints

​Storefronts

​Inventory Sources

​Storefront Billing

​MCP Tools

​Supported Endpoint Families

​Response Format

​Support

Storefront API Reference

Overview

Connection Methods

REST API (Recommended for traditional integrations)

MCP (Model Context Protocol) for AI Agents

OpenAPI Specification

Authentication

Storefront Capabilities

REST API Endpoints

Storefronts

Inventory Sources

Storefront Billing

MCP Tools

Supported Endpoint Families

Response Format

Support