Scope3 Storefronts API

openapi: 3.2.0
info:
  title: Scope3 Buyer Storefronts API
  version: 2.0.0
  description: 'REST API for advertisers to manage advertisers, campaigns, and reporting.


    ## Authentication


    All endpoints require a Bearer token in the Authorization header:

    ```

    Authorization: Bearer your-api-key

    ```


    ## Base URL


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


    ## For AI Agents


    AI agents can use the MCP endpoint at `/mcp/v2/buyer` with three tools:

    - `initialize`: Start an MCP session

    - `api_call`: Make REST API calls

    - `ask_about_capability`: Learn about API features'
servers:
- url: https://api.interchange.io/api/v2/buyer
  description: Production server
tags:
- name: Storefronts
paths:
  /storefronts:
    get:
      operationId: listStorefronts
      summary: List storefronts
      description: List all enabled storefronts visible to the buyer. Each storefront contains inventory sources backed by agents.
      tags:
      - Storefronts
      security:
      - bearerAuth: []
      parameters:
      - in: query
        name: name
        schema:
          description: Filter by storefront name (partial match, case-insensitive)
          type: string
        description: Filter by storefront name (partial match, case-insensitive)
      - in: query
        name: status
        schema:
          description: Filter by stored-control labels. `neutral` and `paused` match `isPaused`; legacy `configuring` and `transacting` match the compatibility field; `archived` matches archived storefronts. This is not transaction readiness.
          type: string
          enum:
          - configuring
          - transacting
          - archived
          - neutral
          - paused
        description: Filter by stored-control labels. `neutral` and `paused` match `isPaused`; legacy `configuring` and `transacting` match the compatibility field; `archived` matches archived storefronts. This is not transaction readiness.
      - in: query
        name: channel
        schema:
          description: Filter to storefronts that carry this channel. Canonical AdCP values such as `display`, `olv`, and `ctv` are recommended; legacy/custom strings remain accepted for compatibility.
          type: string
          minLength: 1
        description: Filter to storefronts that carry this channel. Canonical AdCP values such as `display`, `olv`, and `ctv` are recommended; legacy/custom strings remain accepted for compatibility.
      - in: query
        name: region
        schema:
          description: Filter to storefronts that accept briefs in this ISO 3166-1 alpha-2 country (e.g. `FR`, `US`, `JP`). Legacy market-group and custom values remain accepted against legacy region declarations.
          type: string
          minLength: 1
        description: Filter to storefronts that accept briefs in this ISO 3166-1 alpha-2 country (e.g. `FR`, `US`, `JP`). Legacy market-group and custom values remain accepted against legacy region declarations.
      - in: query
        name: visibility
        schema:
          description: Which storefronts to list. `public` (default) returns human-reviewed storefronts listed in the buyer marketplace. `private` returns ALL storefronts (configuring, transacting, archived, hidden, or pending review) owned by customers in the caller's parent organization.
          type: string
          enum:
          - public
          - private
      - in: query
        name: publisherDomain
        schema:
          description: Find sellers that represent this publisher. Returns storefronts whose declared publisher coverage includes this domain or any of its subdomains. Use this for vendor selection — identifying which sellers cover a publisher you care about. This is a coverage filter, not an inventory query; for domain-level product availability use product discovery.
          type: string
        description: Find sellers that represent this publisher. Returns storefronts whose declared publisher coverage includes this domain or any of its subdomains. Use this for vendor selection — identifying which sellers cover a publisher you care about. This is a coverage filter, not an inventory query; for domain-level product availability use product discovery.
      - in: query
        name: limit
        schema:
          description: 'Maximum storefronts per page (default: 20, max: 100)'
          type: integer
          maximum: 100
          minimum: 1
        description: 'Maximum storefronts per page (default: 20, max: 100)'
      - in: query
        name: offset
        schema:
          description: 'Number of storefronts to skip for pagination (default: 0)'
          type: integer
          minimum: 0
          maximum: 9007199254740991
        description: 'Number of storefronts to skip for pagination (default: 0)'
      responses:
        '200':
          description: List storefronts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuyerStorefrontList'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /storefronts/{storefrontId}:
    get:
      operationId: getStorefront
      summary: Get storefront
      description: Get a single storefront with rolled-up buyer connection status.
      tags:
      - Storefronts
      security:
      - bearerAuth: []
      parameters:
      - in: path
        name: storefrontId
        schema:
          description: Storefront ID
          type: integer
          maximum: 9007199254740991
          minimum: 1
        required: true
        description: Storefront ID
      responses:
        '200':
          description: Get storefront
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuyerStorefront'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /storefronts/{storefrontId}/capabilities:
    get:
      operationId: getStorefrontCapabilities
      summary: Get storefront capabilities
      description: Inspect source-level capability diagnostics for a buyer-visible storefront.
      tags:
      - Storefronts
      security:
      - bearerAuth: []
      parameters:
      - in: path
        name: storefrontId
        schema:
          description: Storefront ID
          type: integer
          maximum: 9007199254740991
          minimum: 1
        required: true
        description: Storefront ID
      responses:
        '200':
          description: Get storefront capabilities
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuyerStorefrontCapabilitiesResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /storefront-connections:
    get:
      operationId: listStorefrontConnections
      summary: List storefront connections
      description: List storefront connection rows and buyer-controlled feature policies. Adapter storefronts include delegated auth status; all storefronts include buy, event, and feed sharing settings.
      tags:
      - Storefronts
      security:
      - bearerAuth: []
      parameters:
      - in: query
        name: storefrontId
        schema:
          description: Optional storefront ID filter
          type: integer
          maximum: 9007199254740991
          minimum: 1
        description: Optional storefront ID filter
      responses:
        '200':
          description: List storefront connections
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StorefrontConnectionsResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /storefront-connection-account-mappings:
    get:
      operationId: listStorefrontConnectionAccountMappings
      summary: List external account mappings
      description: List external provider accounts across integrations with source-scoped advertiser mappings.
      tags:
      - Storefronts
      security:
      - bearerAuth: []
      parameters:
      - in: query
        name: search
        schema:
          description: Optional search over provider, connection, external account name, and external account ID.
          type: string
        description: Optional search over provider, connection, external account name, and external account ID.
      - in: query
        name: provider
        schema:
          description: Optional provider type filter, such as google or meta.
          type: string
        description: Optional provider type filter, such as google or meta.
      - in: query
        name: advertiserId
        schema:
          description: Optional mapped advertiser ID filter.
          type: string
          pattern: ^\d+$
        description: Optional mapped advertiser ID filter.
      - in: query
        name: storefrontId
        schema:
          description: Optional storefront ID filter for embedded connection views.
          type: string
          pattern: ^\d+$
        description: Optional storefront ID filter for embedded connection views.
      - in: query
        name: mappingStatus
        schema:
          description: Filter by mapping state. 'unreachable' returns only preserved mappings whose platform account no active connection reaches (relink to restore).
          default: all
          type: string
          enum:
          - all
          - mapped
          - unmapped
          - unreachable
        description: Filter by mapping state. 'unreachable' returns only preserved mappings whose platform account no active connection reaches (relink to restore).
      - in: query
        name: limit
        schema:
          default: 50
          type: integer
          maximum: 100
          minimum: 1
      - in: query
        name: offset
        schema:
          default: 0
          type: integer
          minimum: 0
          maximum: 9007199254740991
      responses:
        '200':
          description: List external account mappings
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StorefrontConnectionAccountMappingsResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /storefront-connections/{connectionId}/accounts:
    get:
      operationId: listStorefrontConnectionAccounts
      summary: List integration external accounts
      description: List external provider accounts discovered for a buyer integration connection, including advertiser mappings.
      tags:
      - Storefronts
      security:
      - bearerAuth: []
      parameters:
      - in: path
        name: connectionId
        schema:
          description: Storefront connection ID
          type: integer
          format: int64
        required: true
        description: Storefront connection ID
      responses:
        '200':
          description: List integration external accounts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StorefrontConnectionAccountsResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /storefront-connections/{connectionId}:
    delete:
      operationId: removeStorefrontConnection
      summary: Remove storefront connection
      description: 'Archive a buyer integration connection to an adapter storefront. Returns `{ archived: true }` with status 200 (not 204).'
      tags:
      - Storefronts
      security:
      - bearerAuth: []
      parameters:
      - in: path
        name: connectionId
        schema:
          description: Storefront connection ID
          type: integer
          format: int64
        required: true
        description: Storefront connection ID
      responses:
        '200':
          description: Remove storefront connection
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StorefrontConnectionArchived'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /storefront-connections/{connectionId}/accounts/{accountId}/select:
    patch:
      operationId: selectStorefrontConnectionAccount
      summary: Select integration external account
      description: Mark one discovered external provider account as the selected account for a buyer integration connection.
      tags:
      - Storefronts
      security:
      - bearerAuth: []
      parameters:
      - in: path
        name: connectionId
        schema:
          description: Storefront connection ID
          type: integer
          format: int64
        required: true
        description: Storefront connection ID
      - in: path
        name: accountId
        schema:
          description: Storefront connection account ID
          type: integer
          format: int64
        required: true
        description: Storefront connection account ID
      responses:
        '200':
          description: Select integration external account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StorefrontConnectionAccount'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /storefront-connections/{connectionId}/accounts/{accountId}/advertiser:
    post:
      operationId: mapStorefrontConnectionAccountToAdvertiser
      summary: Map external account to advertiser
      description: Map an external provider account discovered through an integration to a buyer advertiser.
      tags:
      - Storefronts
      security:
      - bearerAuth: []
      parameters:
      - in: path
        name: connectionId
        schema:
          description: Storefront connection ID
          type: integer
          format: int64
        required: true
        description: Storefront connection ID
      - in: path
        name: accountId
        schema:
          description: Storefront connection account ID
          type: integer
          format: int64
        required: true
        description: Storefront connection account ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                advertiserId:
                  description: Numeric advertiser ID to map this provider account to
                  type: string
                  pattern: ^\d+$
                sourceId:
                  description: Optional adapter provider ID for compatibility. Official adapter mappings derive the canonical provider ID from connectionId; when supplied, use the canonical value returned by the mappings list (for example, meta). Historical adapter/platform aliases remain accepted.
                  type: string
                  minLength: 1
              required:
              - advertiserId
              additionalProperties: false
      responses:
        '201':
          description: Map external account to advertiser
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountOutput'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /storefront-connections/{connectionId}/accounts/{accountId}/directed-campaigns/subscribe:
    post:
      operationId: subscribeDirectedCampaigns
      summary: Subscribe a directed-campaign account (alpha)
      description: Subscribe an advertiser-mapped adapter account, enumerate its upstream campaigns, and persist one read-only directed campaign per upstream media buy with a one-year historical window. PostHog-gated alpha.
      tags:
      - Storefronts
      security:
      - bearerAuth: []
      parameters:
      - in: path
        name: connectionId
        schema:
          description: Storefront connection ID
          type: integer
          format: int64
        required: true
        description: Storefront connection ID
      - in: path
        name: accountId
        schema:
          description: Storefront connection account ID
          type: integer
          format: int64
        required: true
        description: Storefront connection account ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscribeDirectedCampaignsBody'
      responses:
        '201':
          description: Subscribe a directed-campaign account (alpha)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscribeDirectedCampaignsResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: The directed-campaigns alpha is not enabled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The connection account was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /storefront-connections/{connectionId}/accounts/{accountId}/directed-campaigns/subscription:
    get:
      operationId: getDirectedCampaignSubscription
      summary: Get directed-campaign subscription health (alpha)
      description: Read subscription state, backfill boundary, freshness, and the latest sync outcome for one connected account.
      tags:
      - Storefronts
      security:
      - bearerAuth: []
      parameters:
      - in: path
        name: connectionId
        schema:
          description: Storefront connection ID
          type: integer
          format: int64
        required: true
        description: Storefront connection ID
      - in: path
        name: accountId
        schema:
          description: Storefront connection account ID
          type: integer
          format: int64
        required: true
        description: Storefront connection account ID
      responses:
        '200':
          description: Get directed-campaign subscription health (alpha)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DirectedCampaignSubscription'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      operationId: unsubscribeDirectedCampaigns
      summary: Unsubscribe a directed-campaign account (alpha)
      description: Stop account mirroring and retire its directed campaign mirrors. Available even after feature exposure is removed.
      tags:
      - Storefronts
      security:
      - bearerAuth: []
      parameters:
      - in: path
        name: connectionId
        schema:
          description: Storefront connection ID
          type: integer
          format: int64
        required: true
        description: Storefront connection ID
      - in: path
        name: accountId
        schema:
          description: Storefront connection account ID
          type: integer
          format: int64
        required: true
        description: Storefront connection account ID
      responses:
        '200':
          description: Unsubscribe a directed-campaign account (alpha)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnsubscribeDirectedCampaignsResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /storefront-connections/{connectionId}/accounts/{accountId}/presences:
    get:
      operationId: listStorefrontConnectionAccountPresences
      summary: List account presences (alpha)
      description: 'List seller-discovered ("tracked") and buyer-pushed audiences/event sources for one connected account. Reference-only: identity, sync status, and counts -- never member lists or event payloads. Requires the directed-campaigns alpha flag.'
      tags:
      - Storefronts
      security:
      - bearerAuth: []
      parameters:
      - in: query
        name: take
        schema:
          description: Number of results to return (max 250)
          example: 50
          default: 50
          type: integer
          maximum: 250
          minimum: 1
        description: Number of results to return (max 250)
      - in: query
        name: skip
        schema:
          description: Number of results to skip for pagination
          example: 0
          default: 0
          type: integer
          minimum: 0
          maximum: 9007199254740991
        description: Number of results to skip for pagination
      - in: query
        name: objectType
        schema:
          description: Filter to one presence object type.
          type: string
          enum:
          - audience
          - event_source
        description: Filter to one presence object type.
      - in: query
        name: includeRetired
        schema:
          description: Include retired (terminal) presence edges. Defaults to false.
          default: 'false'
          type: string
          enum:
          - 'true'
          - 'false'
        description: Include retired (terminal) presence edges. Defaults to false.
      - in: path
        name: connectionId
        schema:
          description: Storefront connection ID
          type: integer
          format: int64
        required: true
        description: Storefront connection ID
      - in: path
        name: accountId
        schema:
          description: Storefront connection account ID
          type: integer
          format: int64
        required: true
        description: Storefront connection account ID
      responses:
        '200':
          description: List account presences (alpha)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StorefrontPresenceListResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Directed campaigns are not enabled for this customer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The connection account was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /storefronts/{storefrontId}/connection-policy:
    patch:
      operationId: updateStorefrontConnectionPolicy
      summary: Update storefront connection policy
      description: 'Update buyer-controlled feature settings for a storefront: whether to buy from it, send event/CAPI signals, and share transformed catalog feeds.'
      tags:
      - Storefronts
      security:
      - bearerAuth: []
      parameters:
      - in: path
        name: storefrontId
        schema:
          description: Storefront ID
          type: integer
          maximum: 9007199254740991
          minimum: 1
        required: true
        description: Storefront ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                buyEnabled:
                  description: Whether this buyer account should buy through this integration.
                  type: boolean
                eventsEnabled:
                  description: Whether this integration should receive buyer event/CAPI signals.
                  type: boolean
                feedsEnabled:
                  description: Whether buyer audience and feed data should be shared with this integration.
                  type: boolean
              additionalProperties: false
      responses:
        '200':
          description: Update storefront connection policy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StorefrontConnectionFeaturePolicy'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /storefronts/{storefrontId}/connection:
    post:
      operationId: connectStorefront
      summary: Connect storefront
      description: Create (or resume) a buyer integration connection to an adapter storefront (Reddit, Snap, Meta, TikTok, Pinterest, Spotify, Google, Amazon, …). Returns the existing connection summary (if any) plus a `connectionUrl` browser handoff — share that URL with the human buyer to complete OAuth or token entry.
      tags:
      - Storefronts
      security:
      - bearerAuth: []
      parameters:
      - in: path
        name: storefrontId
        schema:
          description: Storefront ID
          type: integer
          maximum: 9007199254740991
          minimum: 1
        required: true
        description: Storefront ID
      responses:
        '200':
          description: Connect storefront
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StorefrontConnectionHandoff'
        '400':
          description: The storefront is not a connectable adapter storefront.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /storefronts/credentials:
    get:
      operationId: listStorefrontCredentials
      summary: List credentials
      description: List all credentials the buyer has registered, scoped to the storefront sources each credential gives access to.
      tags:
      - Storefronts
      security:
      - bearerAuth: []
      responses:
        '200':
          description:

# --- truncated at 32 KB (145 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/scope3/refs/heads/main/openapi/scope3-storefronts-api-openapi.yml