> ## Documentation Index
> Fetch the complete documentation index at: https://docs.interchange.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Storefront API Reference

> Interchange Storefront API reference documentation for publishers and technology partners

# 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

<Tabs>
  <Tab title="REST API">
    ### REST API (Recommended for traditional integrations)

    Standard HTTP methods with JSON request/response bodies.

    **Production:**

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

    **Example:**

    ```bash theme={null}
    curl https://api.interchange.io/api/v2/storefront \
      -H "Authorization: Bearer scope3_your_api_key_here"
    ```
  </Tab>

  <Tab title="MCP (AI Agents)">
    ### 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
    ```
  </Tab>
</Tabs>

## OpenAPI Specification

Download the OpenAPI specification for SDK generation or API exploration:

* **Production:** [/api/v2/storefront/openapi.yaml](https://api.interchange.io/api/v2/storefront/openapi.yaml)

## Authentication

All API requests require authentication using your Interchange API key:

```bash theme={null}
Authorization: Bearer scope3_your_api_key_here
```

<Card title="Get API Key" href="https://interchange.io/user-api-keys" icon="key">
  Request API credentials to get started
</Card>

## 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:**

```bash theme={null}
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:**

```bash theme={null}
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:**

```bash theme={null}
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:**

```bash theme={null}
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:**

```bash theme={null}
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:**

```bash theme={null}
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:**

```bash theme={null}
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:**

```bash theme={null}
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.                                                                                                                                                                                            |

<Note>
  **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`).
</Note>

### 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:

```json theme={null}
{
  "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:

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

**Error Response:**

```json theme={null}
{
  "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](mailto:support@scope3.com).