Scope3 Storefront API

openapi: 3.2.0
info:
  title: Scope3 Storefront API
  version: 2.0.0
  description: 'REST API for partners to manage storefronts, inventory sources, and billing.


    ## Authentication


    All endpoints require a Bearer token in the Authorization header:

    ```

    Authorization: Bearer your-api-key

    ```


    ## Base URL


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


    ## For AI Agents


    AI agents can use the MCP endpoint at `/mcp/v2/storefront` 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/storefront
  description: Production server
tags:
- name: Storefront
  description: Manage storefront and inventory sources
paths:
  /account-mappings/summary:
    get:
      operationId: getSellerAccountMappingSummary
      summary: Get seller account mapping summary
      description: Get seller-owned relationship and active inventory-source coverage counts for the Buyer Account Mapping Page.
      tags:
      - Storefront
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Get seller account mapping summary
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SellerAccountMappingSummary'
        '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'
  /account-mappings:
    get:
      operationId: listSellerAccountRelationships
      summary: List seller account relationships
      description: List the seller-owned operator-and-brand relationships and their private coverage across active inventory sources.
      tags:
      - Storefront
      security:
      - bearerAuth: []
      parameters:
      - in: query
        name: offset
        schema:
          default: 0
          type: integer
          minimum: 0
          maximum: 9007199254740991
      - in: query
        name: limit
        schema:
          default: 50
          type: integer
          minimum: 1
          maximum: 100
      - in: query
        name: search
        schema:
          type: string
          maxLength: 200
      responses:
        '200':
          description: List seller account relationships
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SellerAccountMappingList'
        '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'
  /account-mappings/export:
    get:
      operationId: exportSellerAccountMappings
      summary: Export seller account mappings
      description: Export the normalized source-mapping template, current healthy mappings, and active source-account choices as formula-safe, byte-bounded CSV documents.
      tags:
      - Storefront
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Export seller account mappings
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SellerAccountMappingExport'
        '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'
  /account-mappings/reviews:
    get:
      operationId: listSellerAccountGrantReviews
      summary: List pending buyer account requests
      description: List buyer account requests awaiting a seller decision, including the optimistic-lock version required for each decision.
      tags:
      - Storefront
      security:
      - bearerAuth: []
      parameters:
      - in: query
        name: offset
        schema:
          default: 0
          type: integer
          minimum: 0
          maximum: 9007199254740991
      - in: query
        name: limit
        schema:
          default: 50
          type: integer
          minimum: 1
          maximum: 100
      responses:
        '200':
          description: List pending buyer account requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SellerAccountGrantReviewList'
        '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'
  /account-mappings/reviews/{grantId}/decision:
    post:
      operationId: decideSellerAccountGrantReview
      summary: Decide a pending buyer account request
      description: Approve a pending buyer account request for Interchange-cleared billing, or reject it with a required reason. The expected version prevents decisions against stale review state.
      tags:
      - Storefront
      security:
      - bearerAuth: []
      parameters:
      - in: path
        name: grantId
        schema:
          anyOf:
          - type: integer
            format: int64
          - type: string
          - type: number
        required: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DecideSellerAccountGrantReviewBody'
      responses:
        '200':
          description: Decide a pending buyer account request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SellerAccountGrantReviewDecision'
        '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'
  /account-mappings/sources/{inventorySourceId}/refresh:
    post:
      operationId: refreshSellerAccountSourceAccounts
      summary: Refresh managed ad-server account choices
      description: Refresh the authenticated, bounded advertiser roster for one managed Google Ad Manager or FreeWheel inventory source. Other managed providers and modular sources fail closed.
      tags:
      - Storefront
      security:
      - bearerAuth: []
      parameters:
      - in: path
        name: inventorySourceId
        schema:
          anyOf:
          - type: integer
            format: int64
          - type: string
          - type: number
        required: true
      responses:
        '200':
          description: Refresh managed ad-server account choices
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManagedSourceAccountRefreshResult'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Inventory source not found for this storefront.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /account-mappings/imports/prepare:
    post:
      operationId: prepareSellerAccountBindingFeed
      summary: Prepare a private seller account mapping feed upload
      description: ADMIN-only. Reserve an immutable feed revision and return a short-lived signed PUT capability for exactly one source_account_bindings.csv. The upload bucket is private and lifecycle-deleted.
      tags:
      - Storefront
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PrepareSellerAccountBindingFeed'
      responses:
        '200':
          description: Prepare a private seller account mapping feed upload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SellerAccountBindingFeedPrepareResult'
        '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: Admin role required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /account-mappings/imports/{revisionId}/preview:
    post:
      operationId: previewSellerAccountBindingFeed
      summary: Validate and preview a seller account mapping feed
      description: ADMIN-only. Verify the immutable uploaded object, quarantine invalid rows, and issue a short-lived preview token tied to the exact mapping state and impact.
      tags:
      - Storefront
      security:
      - bearerAuth: []
      parameters:
      - in: path
        name: revisionId
        schema:
          type: string
          format: uuid
          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
        required: true
      responses:
        '200':
          description: Validate and preview a seller account mapping feed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SellerAccountBindingFeedPreviewResult'
        '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: Admin role required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /account-mappings/imports/{revisionId}/commit:
    post:
      operationId: commitSellerAccountBindingFeed
      summary: Atomically commit a seller account mapping feed
      description: ADMIN-only. Apply the exact reviewed mapping set with compare-and-swap guards. Manual mappings and mappings owned by another feed are never overwritten; snapshot omissions affect only mappings owned by this feed.
      tags:
      - Storefront
      security:
      - bearerAuth: []
      parameters:
      - in: path
        name: revisionId
        schema:
          type: string
          format: uuid
          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
        required: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CommitSellerAccountBindingFeed'
      responses:
        '200':
          description: Atomically commit a seller account mapping feed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SellerAccountBindingFeedCommitResult'
        '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: Admin role required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /account-mappings/imports/{revisionId}:
    get:
      operationId: getSellerAccountBindingFeedRevision
      summary: Get seller account mapping feed revision status
      description: ADMIN-only. Read the tenant-scoped lifecycle, diagnostics, and impact of one source-account mapping feed revision.
      tags:
      - Storefront
      security:
      - bearerAuth: []
      parameters:
      - in: path
        name: revisionId
        schema:
          type: string
          format: uuid
          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
        required: true
      responses:
        '200':
          description: Get seller account mapping feed revision status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SellerAccountBindingFeedRevision'
        '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: Admin role required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /storefront:
    servers:
    - url: https://api.interchange.io/api/v2
      description: Production server
    get:
      operationId: getStorefront
      summary: Get storefront
      description: Get the authenticated customer's storefront.
      tags:
      - Storefront
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Get storefront
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StorefrontResponse'
        '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'
    post:
      operationId: createStorefront
      summary: Create storefront
      description: 'Create the authenticated customer''s storefront. A name and a publisher domain are required — the publisher domain is the identity buyers and partners look the storefront up by. Idempotent: when a storefront already exists for the customer, it is returned unchanged (200) instead of creating a duplicate.'
      tags:
      - Storefront
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateStorefrontBody'
      responses:
        '200':
          description: A storefront already exists for this account — returned unchanged (idempotent create; the request body is not applied).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StorefrontResponse'
        '201':
          description: Create storefront
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StorefrontResponse'
        '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'
    put:
      operationId: updateStorefront
      summary: Update storefront
      description: Update the storefront configuration.
      tags:
      - Storefront
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  description: Updated display name
                  example: Acme Media Network
                  type: string
                  minLength: 1
                  maxLength: 255
                publisherDomain:
                  description: Deprecated legacy singular publisher domain. Use businessProfile.publisherDomains / publisher-domain sync state for the storefront publisher-domain set.
                  type: string
                  minLength: 1
                  maxLength: 255
                plan:
                  description: Updated plan tier
                  type: string
                  enum:
                  - basic
                transacting:
                  description: Deprecated compatibility alias for the inverse of `isPaused`. It is not effective transaction availability.
                  type: boolean
                isPaused:
                  description: Compatibility-named seller intake hold. True hides product discovery and blocks new media buys and buyer edits; approved unsent buys wait until it is false. It does not pause existing ad-server delivery. New storefronts default to false; effective transaction availability also depends on readiness and archival state.
                  type: boolean
                sellsThirdPartyInventory:
                  description: Set to `true` to also resell third-party inventory from other Interchange storefronts; `false` to sell only the storefront’s own inventory sources.
                  type: boolean
                defaultCurrency:
                  description: Seller-confirmed settlement currency (ISO-4217). Required before go-live for Interchange-cleared storefronts; never defaulted silently. Direct sales adapter storefronts run by our expert agents skip settlement-currency readiness checks because Interchange does not pay the seller on that path.
                  example: EUR
                  type: string
                  pattern: ^[A-Z]{3}$
                paymentCurrencies:
                  description: ISO-4217 currencies this storefront will be paid in (the payout set). A media buy settles in one of these (the primary defaultCurrency is always included). The buyer payment currency is the seller payout currency unless the marketplace accepts the buyer currency via cross-currency FX, in which case the source cost is converted to the buyer currency at the platform spot rate while the source is still paid in one of these currencies. A pricing option may not use a settlement currency outside this set. Empty falls back to defaultCurrency, so a single-currency storefront need not set it. Duplicates are ignored.
                  example:
                  - USD
                  - GBP
                  maxItems: 25
                  type: array
                  items:
                    type: string
                    pattern: ^[A-Z]{3}$
                acceptedCountries:
                  description: Replace the operator-confirmed exhaustive country allowlist used to route briefs. This is acceptance policy, not Media Kit merchandising. Pass null to mark the scope unconfigured.
                  example:
                  - FR
                  minItems: 1
                  maxItems: 249
                  type:
                  - array
                  - 'null'
                  items:
                    type: string
                    pattern: ^[A-Z]{2}$
                acceptsAllCountries:
                  description: 'Set true to accept briefs from every country. Set false with acceptedCountries: null to clear routing scope to unconfigured.'
                  type: boolean
                advertisingPolicyDisclosure:
                  description: Business Rules sections to publish as Advertising Policies on the Discovery Card. Empty hides the disclosure. Approval routing, review mode, and revision notes are never published. Read-only for pass-through storefronts, whose policy comes from upstream AdCP capabilities.
                  maxItems: 2
                  type: array
                  items:
                    description: A Business Rules section the seller elects to disclose publicly as Advertising Policies on its Discovery Card.
                    type: string
                    enum:
                    - brief_acceptance
                    - creative_policy
                supportedLanguages:
                  description: Languages (BCP-47) the co-branded join/signup surface may localize within.
                  example:
                  - nl
                  - fr
                  - en
                  type: array
                  items:
                    type: string
                    minLength: 2
                    maxLength: 35
                operatorDomain:
                  description: Canonical operator domain for AAO registry lookup. Changing it invalidates description, channels, membershipStatus, and website values curated for the prior identity. Resupply valid values in the same request or acknowledge their removal with confirmOperatorDomainProfileReset.
                  example: scope3.com
                  type: string
                  minLength: 1
                  maxLength: 255
                confirmOperatorDomainProfileReset:
                  description: 'Required when changing operatorDomain would clear profile fields curated for the previous identity: description, channels, membershipStatus, or website. Fields explicitly resupplied in the same request are preserved/replaced. Ignored when the domain is unchanged or no populated fields would be cleared.'
                  type: boolean
                brandName:
                  description: Brand name resolved from AAO registry
                  example: Scope3
                  type: string
                  maxLength: 255
                logoUrl:
                  description: Logo URL resolved from brand.json
                  type: string
                  maxLength: 2048
                  format: uri
                logoBackground:
                  description: Backdrop the resolved logo is designed for, from brand.json. Drives the storefront card tile color. Pass null to clear.
                  type:
                  - string
                  - 'null'
                  enum:
                  - dark-bg
                  - light-bg
                  - transparent-bg
                membershipStatus:
                  description: AAO membership tier displayed on the storefront card. Use `NONE` to hide the badge.
                  type: string
                  enum:
                  - AAO_FOUNDING_MEMBER
                  - AAO_MEMBER
                  - NONE
                regions:
                  description: Compatibility write alias for legacy businessProfile.regions merchandising context. It does not route briefs or define Discovery Card country coverage. Prefer businessProfile.regions when maintaining legacy context.
                  example:
                  - NL
                  - BE
                  - WORLDWIDE
                  maxItems: 64
                  type: array
                  items:
                    type: string
                    pattern: ^[A-Z0-9_-]{2,32}$
                description:
                  description: Operator-curated description shown on the storefront card. Overrides brand.json when set.
                  type:
                  - string
                  - 'null'
                  maxLength: 2000
                channels:
                  description: ADCP channel codes the storefront offers. Surfaced on the storefront card.
                  example:
                  - display
                  - olv
                  - ctv
                  maxItems: 16
                  type: array
                  items:
                    description: Legacy V2 storefront channel code. Values round-trip unchanged; the Discovery Card projection, Marketplace filters, and outbound AdCP capabilities normalize `audio` to canonical `streaming_audio`.
                    type: string
                    enum:
                    - display
                    - olv
                    - ctv
                    - social
                    - audio
                    - dooh
                website:
                  description: Operator-curated website URL shown on the storefront card. Overrides brand.json when set.
                  type: string
                  maxLength: 2048
                  format: uri
                demandContactName:
                  description: Name of the person at the publisher who fields buyer inquiries (RFPs, prospective briefs, weekly digests). Must be set together with `demandContactEmail`. Pass null to clear (both fields must be cleared together).
                  example: Pia Eberhardt
                  type:
                  - string
                  - 'null'
                  minLength: 1
                  maxLength: 255
                demandContactEmail:
                  description: Email address for the demand contact. Must be set together with `demandContactName`. Pass null to clear (both fields must be cleared together).
                  example: pia@nrcmediagroep.com
                  type:
                  - string
                  - 'null'
                  maxLength: 320
                  format: email
                  pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
                capabilities:
                  description: Legacy v2 capability object. All flags remain persisted for compatibility, but the effective `offersProductComposition` response and runtime behavior are derived from merchandising access and ready Source product paths. V3 publishes the optional deprecated boolean as a typed no-op, strips it before dispatch, and reports it as ignored.
                  type: object
                  properties:
                    offersCreativeReview:
                      description: Surfaces the creative review protocol surface to buyers. `sync_creatives` returns review-status fields; inline creatives in `create_media_buy` / `update_media_buy` flow through the storefront review gate. The operator policy (auto-approve vs manual queue) is separate config — this flag only governs whether the capability is advertised.
                      default: false
                      type: boolean
                    offersCampaignApproval:
                      description: Surfaces the campaign approval protocol surface to buyers. `create_media_buy` and material-change `update_media_buy` may return a submitted-task envelope until the operator decides. The operator policy (auto-approve vs manual queue, material-change threshold) is separate config.
                      default: false
                      type: boolean
                    offersProductComposition:
                      deprecated: true
                      description: Read-only compatibility projection. True only while the customer has merchandising access and at least one active Source has a ready Storefront-built product path (`WHOLESALE`).
                      default: false
                      type: boolean
                setupIntent:
                  description: 'Record the operator''s declared selling intent. This is descriptive state only: it does not change Source product paths or effective capabilities. Both ''sell_through_scope3'' and ''third_party_connect'' are accepted regardless of current Source types.'
                  type: string
                  enum:
                  - third_party_connect
                  - sell_through_scope3
                compositionPricing:
                  description: 'Replace storefront composition pricing settings: fallback pricing percentile plus seller pricing facts extracted from rate cards, media kits, or operator instructions.'
                  allOf:
                  - $ref: '#/components/schemas/StorefrontCompositionPricing'
                creativeApproval:
                  description: 'Operator setting: how creatives buyers submit are handled on ad-server-backed inventory sources. `manual` queues each for review; `auto` approves without review. External sales agents and linked Storefronts keep their own approval settings.'
                  type: string
                  enum:
                  - auto
                  - manual
                mediaBuyApproval:
                  description: 'Operator setting: how new media buys are handled on ad-server-backed inventory sources. `manual` queues each for review; `auto` lets the buy start without review. External sales agents and linked Storefronts keep their own approval settings.'
                  type: string
                  enum:
                  - auto
                  - manual
                businessProfile:
                  description: Whole-document replacement for the operator-supplied business profile captured during Murph-led setup. New evidence URLs must use HTTP(S); a previously stored legacy URI may be submitted unchanged so read/mod

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