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

# Get storefront

> Get a single storefront with rolled-up buyer connection status.



## OpenAPI

````yaml /v2/buyer-api-v2.yaml get /storefronts/{storefrontId}
openapi: 3.0.0
info:
  title: Scope3 Buyer 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
security: []
tags:
  - name: Signup
    description: Request reviewed access to Interchange
  - name: Account
    description: Account management, service tokens, and preferences
  - name: Asks
    description: >-
      What you are waiting on Scope3 for — support, product, and supply asks in
      one list
  - name: Advertisers
    description: Manage advertisers
  - name: Product Discovery
    description: Discover and select products
  - name: Campaigns
    description: Manage advertising campaigns
  - name: Creatives
    description: Build, manage, and sync campaign creatives via AdCP Creative Protocol
  - name: Reporting
    description: Access performance metrics
  - name: Event Sources
    description: >-
      Manage event source configurations and log conversion/marketing events for
      attribution
  - name: Property Lists
    description: Validate property lists against AAO registry
  - name: Sales Agents
    description: View and connect sales agents
  - name: Measurement
    description: Measurement sources, records, context, and freshness
  - name: Syndication
    description: Syndicate resources to ADCP agents
  - name: Tasks
    description: Track async operation status
  - name: Buyer Billing
    description: >-
      Consolidated invoicing for buyers — invoices and pending invoice items
      issued by Scope3 across the buyer customer.
  - name: MCP
    description: Model Context Protocol endpoints for AI agents
paths:
  /storefronts/{storefrontId}:
    get:
      tags:
        - Storefronts
      summary: Get storefront
      description: Get a single storefront with rolled-up buyer connection status.
      operationId: getStorefront
      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'
      security:
        - bearerAuth: []
components:
  schemas:
    BuyerStorefront:
      description: A storefront as seen by a buyer
      type: object
      properties:
        id:
          description: Storefront ID
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        platformId:
          description: Public-facing slug
          type: string
        name:
          description: Storefront display name
          type: string
        publisherDomain:
          description: Publisher domain
          nullable: true
          type: string
        brandName:
          description: >-
            Operator-owned or resolved brand name shown on storefront discovery
            cards.
          nullable: true
          type: string
        logoUrl:
          description: >-
            Operator-owned or resolved logo URL shown on storefront discovery
            cards.
          nullable: true
          type: string
        logoBackground:
          description: >-
            Backdrop the logo is designed for, from brand.json. Null when
            unknown.
          nullable: true
          type: string
        description:
          description: Operator-curated description shown on storefront discovery cards.
          nullable: true
          type: string
        website:
          description: Operator-curated website URL shown on storefront discovery cards.
          nullable: true
          type: string
        brandColors:
          $ref: '#/components/schemas/BuyerStorefrontBrandColors'
        discoveryCard:
          description: >-
            Canonical storefront identity and coverage used by every marketplace
            card renderer.
          allOf:
            - $ref: '#/components/schemas/DiscoveryCard'
        displayStatus:
          description: >-
            Deprecated stored-control label. Legacy projections retain
            `configuring` and `transacting`; projections backed by `isPaused`
            return `neutral` or `paused`. `archived` overrides both. Use
            readiness.effectiveStatus and readiness.canTransact for actual
            availability.
          type: string
          enum:
            - configuring
            - transacting
            - archived
            - neutral
            - paused
        readiness:
          $ref: '#/components/schemas/BuyerStorefrontReadiness'
        channels:
          description: >-
            Ad channels this storefront supports (e.g. "display", "CTV",
            "audio"). Empty array if not specified.
          example:
            - CTV
            - display
          type: array
          items:
            type: string
        adapterProviderType:
          description: >-
            Adapter platform type (e.g. "meta", "tiktok"). Null for non-adapter
            storefronts.
          nullable: true
          type: string
        publishers:
          nullable: true
          type: object
          properties:
            total:
              type: integer
              minimum: 0
              maximum: 9007199254740991
            verified:
              type: integer
              minimum: 0
              maximum: 9007199254740991
            sample:
              type: array
              items:
                type: string
          required:
            - total
            - verified
            - sample
          additionalProperties: false
        adapterSourceKind:
          description: >-
            Adapter family for official adapter storefronts, such as sales or
            creative. Null for non-adapter storefronts.
          nullable: true
          type: string
          enum:
            - sales
            - creative
            - signals
            - measurement
            - optimization
            - composite
        creativeCapabilities:
          description: >-
            Creative-generation capabilities when this is a creative adapter
            storefront; null otherwise.
          nullable: true
          allOf:
            - $ref: '#/components/schemas/BuyerCreativeStorefrontCapability'
        adapterConnection:
          description: >-
            Buyer-specific connection state for official adapter storefronts;
            null for non-adapter storefronts or when connection state was not
            requested.
          nullable: true
          allOf:
            - $ref: '#/components/schemas/BuyerAdapterConnectionStatus'
        supportedRoutingTypes:
          deprecated: true
          description: >-
            Deprecated v2 compatibility placeholder. Every storefront returns
            both legacy values. Do not use this field for storefront type,
            targeting, eligibility, execution, connectivity, or settlement; use
            explicit capabilities, authentication state, and BillingParty
            instead.
          type: array
          items:
            type: string
            enum:
              - DECISIONED
              - ROUTED
        supportedBilling:
          description: >-
            Supported billing parties for media bought from this storefront,
            using AdCP BillingParty vocabulary (who is invoiced): `agent` means
            Interchange clears the transaction and bills the buyer;
            `operator`/`advertiser` mean the seller or connected platform bills
            the account operator or advertiser directly — Interchange never
            touches the media money. Adapter storefronts are always
            `operator`/`advertiser`.
          minItems: 1
          type: array
          items:
            type: string
            enum:
              - operator
              - agent
              - advertiser
        regions:
          description: >-
            Operator-curated regions this storefront covers (ISO 3166-1 alpha-2
            country codes or group codes like WORLDWIDE, EMEA, NORAM). Empty
            array if not specified.
          example:
            - UK
            - EMEA
          type: array
          items:
            type: string
        connected:
          description: >-
            Whether every inventory source the buyer needs is connected. This is
            buyer credential wiring, not storefront transaction readiness; use
            `readiness.canTransact` for availability.
          type: boolean
        requiresCredentials:
          description: >-
            Whether the buyer must register credentials before they can transact
            with this storefront.
          type: boolean
        customerAccounts:
          description: >-
            The buyer's registered accounts for this storefront, aggregated
            across its inventory sources and deduped by accountIdentifier.
          type: array
          items:
            $ref: '#/components/schemas/BuyerStorefrontAccount'
        adcpCapabilities:
          description: >-
            AdCP capability manifest for the storefront's underlying agent(s).
            Non-null for agent-based storefronts with cached capability data;
            null for adapter storefronts or when no capability data has been
            fetched yet.
          nullable: true
          allOf:
            - $ref: '#/components/schemas/BuyerStorefrontAdcpCapabilities'
        discoveryPerformance:
          description: >-
            Observed response-time stats from buyer product discovery. Use this
            to decide whether to ask the user before running a long discovery
            wait.
          allOf:
            - $ref: '#/components/schemas/BuyerStorefrontDiscoveryPerformance'
      required:
        - id
        - platformId
        - name
        - publisherDomain
        - brandName
        - logoUrl
        - logoBackground
        - description
        - website
        - brandColors
        - discoveryCard
        - displayStatus
        - readiness
        - channels
        - adapterProviderType
        - adapterSourceKind
        - creativeCapabilities
        - adapterConnection
        - supportedRoutingTypes
        - supportedBilling
        - regions
        - connected
        - requiresCredentials
        - customerAccounts
        - adcpCapabilities
        - discoveryPerformance
      additionalProperties: false
    ErrorResponse:
      description: Standard error response
      type: object
      properties:
        data:
          type: string
          nullable: true
          enum:
            - null
        error:
          $ref: '#/components/schemas/ApiError'
      required:
        - data
        - error
      additionalProperties: false
    BuyerStorefrontBrandColors:
      description: >-
        Validated brand.json colors object for rendering buyer discovery cards.
        Null when unresolved.
      nullable: true
      type: object
      additionalProperties:
        type: string
    DiscoveryCard:
      description: >-
        Canonical buyer-visible storefront identity, coverage declaration, and
        optional Advertising Policies disclosure. Unknown coverage never means
        worldwide or all channels.
      type: object
      properties:
        storefrontId:
          type: string
        platformId:
          type: string
        storefrontKind:
          type: string
          enum:
            - managed
            - external_pass_through
        displayName:
          type: string
        logoUrl:
          nullable: true
          type: string
        logoBackground:
          nullable: true
          type: string
          enum:
            - dark-bg
            - light-bg
            - transparent-bg
        description:
          nullable: true
          type: string
        website:
          nullable: true
          type: string
        brandColors:
          nullable: true
          type: object
          additionalProperties:
            type: string
        channels:
          description: >-
            Aggregate channel facets for search and display. Do not combine
            these with aggregate countries as a cross-product coverage promise.
          type: array
          items:
            type: string
        countries:
          description: >-
            Aggregate ISO 3166-1 alpha-2 country facets for search and display.
            Do not combine these with aggregate channels as a cross-product
            coverage promise.
          type: array
          items:
            type: string
            pattern: ^[A-Z]{2}$
        acceptsAllCountries:
          description: >-
            True only when the storefront explicitly accepts briefs from every
            country.
          type: boolean
        coverageDeclarations:
          description: >-
            Channel and country coverage claims preserved at their source
            boundaries. A combined filter matches only when one declaration
            satisfies both dimensions.
          type: array
          items:
            description: >-
              One source-level coverage claim. Channels and countries are
              correlated within this declaration; an empty dimension is unknown,
              not unrestricted.
            type: object
            properties:
              channels:
                description: Channels accepted by this correlated source declaration.
                type: array
                items:
                  type: string
              countries:
                description: >-
                  ISO 3166-1 alpha-2 countries accepted by this correlated
                  source declaration.
                type: array
                items:
                  type: string
                  pattern: ^[A-Z]{2}$
              acceptsAllCountries:
                description: >-
                  True only when this correlated source declaration explicitly
                  accepts every country.
                type: boolean
            required:
              - channels
              - countries
              - acceptsAllCountries
            additionalProperties: false
        advertisingPolicies:
          nullable: true
          type: string
          maxLength: 10000
        coverage:
          type: object
          properties:
            channels:
              type: string
              enum:
                - declared
                - partial
                - unknown
            countries:
              type: string
              enum:
                - declared
                - partial
                - unknown
          required:
            - channels
            - countries
          additionalProperties: false
        provenance:
          type: object
          properties:
            identity:
              type: object
              properties:
                displayName:
                  type: string
                  enum:
                    - operator
                    - registry
                    - upstream_capabilities
                    - unknown
                logoUrl:
                  type: string
                  enum:
                    - operator
                    - registry
                    - upstream_capabilities
                    - unknown
                description:
                  type: string
                  enum:
                    - operator
                    - registry
                    - upstream_capabilities
                    - unknown
                website:
                  type: string
                  enum:
                    - operator
                    - registry
                    - upstream_capabilities
                    - unknown
                brandColors:
                  type: string
                  enum:
                    - operator
                    - registry
                    - upstream_capabilities
                    - unknown
              required:
                - displayName
                - logoUrl
                - description
                - website
                - brandColors
              additionalProperties: false
            coverage:
              type: object
              properties:
                channels:
                  type: string
                  enum:
                    - operator
                    - registry
                    - upstream_capabilities
                    - unknown
                countries:
                  type: string
                  enum:
                    - operator
                    - registry
                    - upstream_capabilities
                    - unknown
              required:
                - channels
                - countries
              additionalProperties: false
            advertisingPolicies:
              type: string
              enum:
                - operator
                - registry
                - upstream_capabilities
                - unknown
          required:
            - identity
            - coverage
            - advertisingPolicies
          additionalProperties: false
      required:
        - storefrontId
        - platformId
        - storefrontKind
        - displayName
        - logoUrl
        - logoBackground
        - description
        - website
        - brandColors
        - channels
        - countries
        - acceptsAllCountries
        - coverageDeclarations
        - advertisingPolicies
        - coverage
        - provenance
      additionalProperties: false
    BuyerStorefrontReadiness:
      description: >-
        Canonical transaction eligibility for this storefront. This is
        independent of buyer credential connection state.
      type: object
      properties:
        canTransact:
          description: >-
            Whether ordinary buyer traffic may currently transact with this
            storefront.
          type: boolean
        effectiveStatus:
          description: >-
            Canonical buyer-facing availability after combining seller controls
            with readiness evidence.
          type: string
          enum:
            - archived
            - paused
            - blocked
            - live
        blockerIds:
          description: >-
            Machine-readable readiness blockers. Empty when effectiveStatus is
            `live`.
          type: array
          items:
            type: string
      required:
        - canTransact
        - effectiveStatus
        - blockerIds
      additionalProperties: false
    BuyerCreativeStorefrontCapability:
      description: >-
        Machine-readable creative generation capability summary for an adapter
        storefront.
      type: object
      properties:
        kind:
          description: Capability kind for creative-generation storefronts.
          type: string
          enum:
            - creative_generation
        modalities:
          description: >-
            Creative media modalities this adapter can generate, such as image,
            audio, or video.
          type: array
          items:
            type: string
            enum:
              - image
              - video
              - audio
        transformerIds:
          description: >-
            Transformer identifiers accepted by this adapter when generating
            creatives. Empty when the adapter discovers transformer details
            dynamically.
          type: array
          items:
            type: string
        supportedFormatIds:
          description: >-
            Representative AdCP creative format IDs this adapter can generate.
            Empty when exact formats must be discovered from
            list_creative_formats.
          type: array
          items:
            type: string
        supportedFormatCount:
          description: >-
            Number of supported AdCP creative formats known without making an
            adapter call.
          type: integer
          minimum: 0
          maximum: 9007199254740991
        supportsBuildCreative:
          description: Whether this storefront exposes build_creative.
          type: boolean
        supportsPreviewCreative:
          description: Whether this storefront exposes preview_creative.
          type: boolean
        formatDiscovery:
          description: How exact creative formats are discovered for this adapter.
          type: string
          enum:
            - canonical
            - static_catalog
            - aao_registry
      required:
        - kind
        - modalities
        - transformerIds
        - supportedFormatIds
        - supportedFormatCount
        - supportsBuildCreative
        - supportsPreviewCreative
        - formatDiscovery
      additionalProperties: false
    BuyerAdapterConnectionStatus:
      description: Buyer-specific delegated-auth status for an official adapter storefront.
      type: object
      properties:
        status:
          description: >-
            Whether this buyer already has delegated credentials for the adapter
            storefront.
          type: string
          enum:
            - not_connected
            - connected
            - needs_account_selection
            - error
        authModes:
          description: Credential flows supported by this adapter storefront for the buyer.
          type: array
          items:
            type: string
            enum:
              - oauth
              - bearer
        accountCount:
          description: >-
            Number of active provider accounts discovered for this buyer
            connection.
          type: integer
          minimum: 0
          maximum: 9007199254740991
        mappedAdvertiserCount:
          description: >-
            Distinct advertisers with an active mapping to one of this
            connection's currently active accounts. 0 on a connected storefront
            means connected-but-not-yet-buyable: a media buy for an unmapped
            advertiser fails with account_mapping_required until it is mapped
            under Settings → Connections.
          default: 0
          type: integer
          minimum: 0
          maximum: 9007199254740991
        selectedAccountName:
          description: Selected provider account display name, if one has been selected.
          nullable: true
          type: string
      required:
        - status
        - authModes
        - accountCount
        - mappedAdvertiserCount
        - selectedAccountName
      additionalProperties: false
    BuyerStorefrontAccount:
      description: A buyer's registered account for a storefront
      type: object
      properties:
        accountIdentifier:
          description: The buyer's account identifier at the source
          type: string
        status:
          description: Account registration status
          type: string
      required:
        - accountIdentifier
        - status
      additionalProperties: false
    BuyerStorefrontAdcpCapabilities:
      description: >-
        AdCP capability manifest for a storefront's underlying agent(s), derived
        from the cached `get_adcp_capabilities` response. Check
        `capabilitiesCachedAt` for data freshness.
      type: object
      properties:
        supportsUpdateMediaBuy:
          description: >-
            Whether the agent declares support for `update_media_buy`. When
            false, buyers should not attempt to modify a campaign after booking.
          type: boolean
        supportsCreateMediaBuy:
          description: Whether the agent declares support for `create_media_buy`.
          type: boolean
        supportsGetReporting:
          description: >-
            Whether the agent supports delivery reporting via
            `get_media_buy_delivery`.
          type: boolean
        supportsSandbox:
          description: >-
            Whether the agent declares sandbox mode — useful for integration
            testing without live spend.
          type: boolean
        extensions:
          description: >-
            AdCP extension identifiers the agent declares support for (e.g.
            `"sandbox"`, `"custom_targeting"`).
          type: array
          items:
            type: string
        protocols:
          description: AdCP protocol versions the agent speaks (e.g. `["adcp-v3"]`).
          type: array
          items:
            type: string
        publisherDomains:
          description: >-
            Publisher domains declared across the storefront’s source-agent
            portfolios.
          type: array
          items:
            type: string
        channels:
          description: >-
            Standard primary channels declared across source-agent portfolios.
            Authoritative for a pure pass-through storefront; inventory evidence
            for managed ingredient sources.
          type: array
          items:
            type: string
        countries:
          description: >-
            Standard primary countries declared across source-agent portfolios.
            Authoritative for a pure pass-through storefront; inventory evidence
            for managed ingredient sources.
          type: array
          items:
            type: string
        countriesComplete:
          description: >-
            Whether every routed source declared at least one primary country.
            False means the country union is partial evidence.
          type: boolean
        channelsComplete:
          description: >-
            Whether every routed source declared at least one primary channel.
            False means the channel union is partial evidence.
          type: boolean
        version:
          description: AdCP version string reported by the agent.
          nullable: true
          type: string
        reportingDeliveryMethods:
          description: >-
            Push-based delivery methods the agent supports for reporting.
            Polling via `get_media_buy_delivery` is always available as a
            baseline. Null when the agent has not declared delivery methods.
          nullable: true
          type: array
          items:
            type: string
            enum:
              - webhook
              - offline
        offlineDeliveryProtocols:
          description: >-
            Cloud storage protocols supported for offline reporting delivery.
            Relevant only when `reportingDeliveryMethods` includes `"offline"`.
            Null when not declared.
          nullable: true
          type: array
          items:
            type: string
            enum:
              - s3
              - gcs
              - azure_blob
        capabilitiesCachedAt:
          description: >-
            When the capability manifest was last fetched from the agent.
            Capabilities are cached up to 24 hours.
          nullable: true
          type: string
          format: date-time
          pattern: >-
            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
      required:
        - supportsUpdateMediaBuy
        - supportsCreateMediaBuy
        - supportsGetReporting
        - supportsSandbox
        - extensions
        - protocols
        - countriesComplete
        - channelsComplete
        - version
        - reportingDeliveryMethods
        - offlineDeliveryProtocols
        - capabilitiesCachedAt
      additionalProperties: false
    BuyerStorefrontDiscoveryPerformance:
      description: Observed buyer product-discovery response timing for this storefront.
      type: object
      properties:
        sampleCount:
          description: Number of buyer discovery responses included in the timing rollup.
          type: integer
          minimum: 0
          maximum: 9007199254740991
        successCount:
          description: Number of successful buyer discovery responses in the timing rollup.
          type: integer
          minimum: 0
          maximum: 9007199254740991
        timeoutCount:
          description: Number of buyer discovery calls that hit the caller wait deadline.
          type: integer
          minimum: 0
          maximum: 9007199254740991
        avgResponseTimeMs:
          description: >-
            Average storefront response time in milliseconds, or null when no
            samples exist.
          nullable: true
          type: integer
          minimum: 0
          maximum: 9007199254740991
        maxResponseTimeMs:
          description: Slowest recorded storefront response time in milliseconds.
          nullable: true
          type: integer
          minimum: 0
          maximum: 9007199254740991
        lastResponseTimeMs:
          description: Most recent recorded storefront response time in milliseconds.
          nullable: true
          type: integer
          minimum: 0
          maximum: 9007199254740991
        lastDiscoveryAt:
          description: When this storefront was last called during buyer product discovery.
          nullable: true
          type: string
          format: date-time
          pattern: >-
            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
      required:
        - sampleCount
        - successCount
        - timeoutCount
        - avgResponseTimeMs
        - maxResponseTimeMs
        - lastResponseTimeMs
        - lastDiscoveryAt
      additionalProperties: false
    ApiError:
      description: Structured error object
      type: object
      properties:
        code:
          description: Machine-readable error code
          type: string
        message:
          description: Human-readable error message
          type: string
        field:
          description: Field path associated with the error
          type: string
        details:
          description: Additional error context
          type: object
          additionalProperties: {}
      required:
        - code
        - message
      additionalProperties: false
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key or access token

````