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

# List storefront connections

> List storefront connection rows and buyer-controlled feature policies. Adapter storefronts include delegated auth status; all storefronts include buy, event, and feed sharing settings. Pass activationStateVersion=2 to accept the deferred activation state.



## OpenAPI

````yaml /v2/buyer-api-v2.yaml get /storefront-connections
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:
  /storefront-connections:
    get:
      tags:
        - Storefronts
      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. Pass
        activationStateVersion=2 to accept the deferred activation state.
      operationId: listStorefrontConnections
      parameters:
        - in: query
          name: storefrontId
          schema:
            description: Optional storefront ID filter
            type: integer
            minimum: 0
            exclusiveMinimum: true
            maximum: 9007199254740991
          description: Optional storefront ID filter
        - in: query
          name: activationStateVersion
          schema:
            description: >-
              Sellers activation-state contract understood by the caller.
              Version 2 adds the deferred state.
            enum:
              - 2
            type: number
          description: >-
            Sellers activation-state contract understood by the caller. Version
            2 adds the deferred state.
      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'
        '409':
          description: >-
            The response contains deferred activation state, but the caller did
            not declare activationStateVersion=2.
          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:
    StorefrontConnectionsResponse:
      type: object
      properties:
        dsEnabled:
          default: false
          type: boolean
        activationStateVersion:
          type: number
          enum:
            - 2
        items:
          type: array
          items:
            $ref: '#/components/schemas/StorefrontConnectionSummary'
      required:
        - dsEnabled
        - items
      additionalProperties: false
      description: Storefront connection rows and control-plane state visible to a buyer.
    ErrorResponse:
      type: object
      properties:
        data:
          type: string
          nullable: true
          enum:
            - null
        error:
          $ref: '#/components/schemas/ApiError'
      required:
        - data
        - error
      additionalProperties: false
      description: Standard error response
    StorefrontConnectionSummary:
      type: object
      properties:
        storefront:
          type: object
          properties:
            id:
              type: string
            platformId:
              type: string
            name:
              type: string
            operatorDomain:
              nullable: true
              type: string
            publisherDomain:
              nullable: true
              type: string
            brandName:
              nullable: true
              type: string
            logoUrl:
              nullable: true
              type: string
            logoBackground:
              nullable: true
              type: string
            brandColors:
              nullable: true
              type: object
              additionalProperties:
                type: string
            description:
              nullable: true
              type: string
            channels:
              type: array
              items:
                type: string
            regions:
              type: array
              items:
                type: string
            website:
              nullable: true
              type: string
            providerType:
              nullable: true
              type: string
            providerDisplayName:
              type: string
            sourceKind:
              nullable: true
              type: string
              enum:
                - sales
                - creative
                - signals
                - measurement
                - optimization
                - composite
            credentialMode:
              nullable: true
              type: string
            routingMode:
              type: string
            agentSources:
              type: array
              items:
                $ref: '#/components/schemas/StorefrontConnectionAgentSource'
          required:
            - id
            - platformId
            - name
            - providerType
            - providerDisplayName
            - sourceKind
            - credentialMode
            - routingMode
            - agentSources
          additionalProperties: false
        status:
          type: string
          enum:
            - not_connected
            - connected
            - needs_account_selection
            - error
        authModes:
          type: array
          items:
            type: string
            enum:
              - oauth
              - bearer
        setupRequired:
          nullable: true
          type: object
          properties:
            code:
              type: string
              enum:
                - oauth_client_not_configured
            message:
              type: string
          required:
            - code
            - message
          additionalProperties: false
        accountCount:
          type: integer
          minimum: 0
          maximum: 9007199254740991
        mappedAdvertiserCount:
          default: 0
          description: >-
            Distinct advertisers with an active mapping to one of this
            connection's accounts.
          type: integer
          minimum: 0
          maximum: 9007199254740991
        campaignsTracked:
          description: >-
            Non-retired tracked campaigns across this connection's accounts. A
            tracked campaign is a campaign the platform did not set up, mirrored
            read-only from a connected provider account. Counts only — spend
            rolls up per account (single currency), never per connection.
          type: integer
          minimum: 0
          maximum: 9007199254740991
        campaignsActive:
          description: >-
            Subset of campaignsTracked whose campaign status is currently
            ACTIVE.
          type: integer
          minimum: 0
          maximum: 9007199254740991
        featurePolicy:
          $ref: '#/components/schemas/StorefrontConnectionFeaturePolicy'
        connection:
          nullable: true
          type: object
          properties:
            id:
              type: string
            storefrontId:
              type: string
            customerId:
              type: integer
              minimum: -9007199254740991
              maximum: 9007199254740991
            kind:
              type: string
            providerType:
              type: string
            sourceKind:
              nullable: true
              type: string
            status:
              type: string
            metadata:
              type: object
              additionalProperties: {}
            createdBy:
              nullable: true
              type: string
            connectedBy:
              nullable: true
              type: string
            archivedAt:
              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))$
            createdAt:
              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))$
            updatedAt:
              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:
            - id
            - storefrontId
            - customerId
            - kind
            - providerType
            - sourceKind
            - status
            - metadata
            - createdBy
            - connectedBy
            - archivedAt
            - createdAt
            - updatedAt
          additionalProperties: false
        credential:
          nullable: true
          type: object
          properties:
            id:
              type: string
            connectionId:
              type: string
            credentialKind:
              type: string
              enum:
                - OAUTH
                - BEARER
                - API_KEY
            scopes:
              type: array
              items:
                type: string
            expiresAt:
              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))$
            lastRefreshedAt:
              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))$
            status:
              type: string
              enum:
                - PENDING
                - ACTIVE
                - EXPIRED
                - REVOKED
                - ERROR
            metadata:
              type: object
              additionalProperties: {}
            connectedBy:
              nullable: true
              type: string
            archivedAt:
              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))$
            createdAt:
              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))$
            updatedAt:
              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:
            - id
            - connectionId
            - credentialKind
            - scopes
            - expiresAt
            - lastRefreshedAt
            - status
            - metadata
            - connectedBy
            - archivedAt
            - createdAt
            - updatedAt
          additionalProperties: false
        selectedAccount:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/StorefrontConnectionAccount'
        controlPlane:
          type: object
          properties:
            selection:
              type: object
              properties:
                selected:
                  type: boolean
                decision:
                  type: string
                  enum:
                    - DEFAULT
                    - ALWAYS_INCLUDE
                    - ALWAYS_EXCLUDE
                reason:
                  type: string
                  enum:
                    - always_include
                    - always_exclude
                    - market_maker
                    - premium_publisher
                    - global_market_maker
                    - regional_market_maker
                    - automatic
                    - default
                selectionVersion:
                  description: >-
                    Opaque desired-selection edge revision as a positive decimal
                    string, or null when no edge exists. It may advance for a
                    fencing bump even when the desired selection is unchanged.
                    If omitted, the version is unknown; not a policy or
                    activation-controller version.
                  nullable: true
                  type: string
                  pattern: ^[1-9]\d*$
                marketplaceReady:
                  type: boolean
                marketplaceUnavailableReason:
                  nullable: true
                  type: string
                  enum:
                    - seller_opted_out
                    - pending_review
                    - not_published
                    - cannot_transact
                automaticGroups:
                  type: array
                  items:
                    type: string
                    enum:
                      - premium_publisher
                      - regional_market_maker
                      - global_market_maker
                marketMakerClassification:
                  nullable: true
                  type: string
                  enum:
                    - regional_market_maker
                    - global_market_maker
                marketMakerProvenance:
                  type: array
                  items:
                    type: object
                    properties:
                      basis:
                        type: string
                        enum:
                          - critical_supply
                          - commercial_entitlement
                          - legacy_regional_flag
                      authority:
                        type: string
                        enum:
                          - manual
                          - contract
                          - beta
                          - regional_flag
                      marketScope:
                        oneOf:
                          - type: object
                            properties:
                              kind:
                                type: string
                                enum:
                                  - GLOBAL
                            required:
                              - kind
                            additionalProperties: false
                          - type: object
                            properties:
                              kind:
                                type: string
                                enum:
                                  - SELECTED_MARKETS
                              markets:
                                type: array
                                items:
                                  type: string
                            required:
                              - kind
                              - markets
                            additionalProperties: false
                        type: object
                      channels:
                        type: array
                        items:
                          type: string
                      expiresAt:
                        nullable: true
                        type: string
                    required:
                      - basis
                      - authority
                      - marketScope
                      - channels
                      - expiresAt
                    additionalProperties: false
              required:
                - selected
                - decision
                - reason
              additionalProperties: false
            billingPolicy:
              type: object
              properties:
                requestedParty:
                  nullable: true
                  type: string
                  enum:
                    - agent
                    - operator
                effectiveParty:
                  nullable: true
                  type: string
                  enum:
                    - agent
                    - operator
                supportedParties:
                  type: array
                  items:
                    type: string
                    enum:
                      - agent
                      - operator
                resolution:
                  type: string
                  enum:
                    - resolved
                    - acceptance_required
                    - unsupported
                    - conflict
                locked:
                  type: boolean
                directBillingAccepted:
                  type: boolean
              required:
                - requestedParty
                - effectiveParty
                - supportedParties
                - resolution
                - locked
                - directBillingAccepted
              additionalProperties: false
            activation:
              type: object
              properties:
                authMode:
                  nullable: true
                  type: string
                  enum:
                    - agent
                    - operator
                state:
                  type: string
                  enum:
                    - provisioning
                    - deferred
                    - active
                    - action_required
                    - waiting_on_seller
                    - retrying
                    - failed
                    - retiring
                    - inactive
                    - not_applicable
                requiredAction:
                  nullable: true
                  type: string
                  enum:
                    - link_account
                    - reconnect
                    - map_account
                    - complete_advertiser_setup
                    - payment_required
                    - accept_direct_billing
                advertisers:
                  type: array
                  items:
                    type: object
                    properties:
                      advertiserId:
                        type: string
                      sellerAccountId:
                        nullable: true
                        type: string
                      preference:
                        type: object
                        properties:
                          decision:
                            type: string
                            enum:
                              - DEFAULT
                              - ENABLED
                              - DISABLED
                          effectiveDesired:
                            type: boolean
                          reason:
                            type: string
                            enum:
                              - hard_ineligibility
                              - account_always_exclude
                              - account_always_include
                              - advertiser_enabled
                              - advertiser_disabled
                              - automatic_match
                              - no_automatic_match
                        required:
                          - decision
                          - effectiveDesired
                          - reason
                        additionalProperties: false
                      qualified:
                        type: boolean
                      eligible:
                        type: boolean
                      state:
                        type: string
                        enum:
                          - provisioning
                          - deferred
                          - active
                          - action_required
                          - waiting_on_seller
                          - retrying
                          - failed
                          - retiring
                          - inactive
                      requiredAction:
                        nullable: true
                        type: string
                        enum:
                          - link_account
                          - reconnect
                          - map_account
                          - complete_advertiser_setup
                          - payment_required
                          - accept_direct_billing
                      actionUrl:
                        nullable: true
                        type: string
                        format: uri
                      failureReason:
                        nullable: true
                        type: string
                        enum:
                          - provisioning_failed
                          - seller_rejected
                          - seller_suspended
                          - seller_closed
                          - invariant_failure
                          - billing_policy_conflict
                          - unsupported_billing
                      diagnosticId:
                        nullable: true
                        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:
                      - advertiserId
                      - sellerAccountId
                      - qualified
                      - eligible
                      - state
                      - requiredAction
                      - failureReason
                    additionalProperties: false
              required:
                - authMode
                - state
                - requiredAction
                - advertisers
              additionalProperties: false
          required:
            - selection
            - billingPolicy
            - activation
          additionalProperties: false
      required:
        - storefront
        - status
        - authModes
        - accountCount
        - mappedAdvertiserCount
        - featurePolicy
        - connection
        - credential
        - selectedAccount
        - controlPlane
      additionalProperties: false
      description: >-
        Buyer-side Storefront connection row with account-level selection and
        billing policy plus aggregate and per-advertiser activation.
    ApiError:
      type: object
      properties:
        code:
          type: string
          description: Machine-readable error code
        message:
          type: string
          description: Human-readable error message
        field:
          description: Field path associated with the error
          type: string
        details:
          description: Additional error context
          type: object
          additionalProperties: {}
      required:
        - code
        - message
      additionalProperties: false
      description: Structured error object
    StorefrontConnectionAgentSource:
      type: object
      properties:
        sourceId:
          type: string
          description: >-
            Canonical provider ID for an official adapter (for example, meta),
            or the inventory source ID for an external AdCP connection.
        name:
          type: string
          description: Display name for the inventory source.
      required:
        - sourceId
        - name
      additionalProperties: false
      description: Agent-backed inventory source eligible for external account mappings.
    StorefrontConnectionFeaturePolicy:
      type: object
      properties:
        buyEnabled:
          type: boolean
          description: Whether this buyer account should buy through this integration.
        eventsEnabled:
          type: boolean
          description: Whether this integration should receive buyer event/CAPI signals.
        feedsEnabled:
          type: boolean
          description: >-
            Whether buyer audience and feed data should be shared with this
            integration.
        updatedAt:
          nullable: true
          description: >-
            When the buyer last customized this policy, or null when defaults
            apply.
          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:
        - buyEnabled
        - eventsEnabled
        - feedsEnabled
        - updatedAt
      additionalProperties: false
      description: Buyer-controlled feature policy for a storefront connection row.
    StorefrontConnectionAccount:
      type: object
      properties:
        id:
          type: string
        connectionId:
          type: string
        credentialId:
          nullable: true
          type: string
        externalAccountId:
          type: string
        name:
          nullable: true
          type: string
        advertiser:
          nullable: true
          description: Provider-reported advertiser identity after safe normalization.
          type: string
        currency:
          nullable: true
          description: Authoritative provider account currency when the adapter reports it.
          type: string
          pattern: ^[A-Z]{3}$
        effectiveTimezone:
          nullable: true
          description: >-
            Seller-effective IANA reporting timezone for this account. Reporting
            calendar boundaries for this account use this value; null when the
            provider has not reported one.
          type: string
        status:
          type: string
          enum:
            - PENDING
            - ACTIVE
            - DISABLED
            - ERROR
        providerStatus:
          nullable: true
          description: Normalized AdCP account status reported by the provider adapter.
          type: string
          enum:
            - active
            - pending_approval
            - payment_required
            - rejected
            - suspended
            - closed
        providerRawStatus:
          nullable: true
          description: >-
            Safe provider-native status value retained for diagnosis, when
            reported.
          anyOf:
            - type: string
            - type: number
        accountType:
          default: null
          description: >-
            Account hierarchy classification from the platform adapter:
            'advertiser' (buyable leaf), 'organization' (manager container —
            never mappable or buyable), or a platform subtype such as
            'sponsored_ads', 'dsp', or 'publisher_identity'. Null for legacy
            rows, treated as a leaf account.
          nullable: true
          type: string
        amazonSponsoredAds:
          nullable: true
          description: >-
            Strict, allowlisted Amazon Ads profile projection. Present only for
            a sponsored_ads account with a valid marketplace ID and
            payment-method signal; null for every other account or malformed
            provider metadata.
          type: object
          properties:
            marketplaceId:
              type: string
              pattern: ^[A-Z0-9]{1,64}$
            countryCode:
              type: string
              pattern: ^[A-Z]{2}$
            validPaymentMethod:
              type: boolean
          required:
            - marketplaceId
            - validPaymentMethod
          additionalProperties: false
        parentExternalId:
          default: null
          description: >-
            External id of the parent account, when known: a manager container
            (Meta Business Manager, Google MCC, Snap Organization, …), or where
            the platform has no manager surface, the owning entity (LinkedIn
            organization; the owning advertiser account for TikTok channel
            identities). Id format is platform-native and may differ from the
            account's own id format.
          nullable: true
          type: string
        parentName:
          default: null
          description: Display name of the parent account, when known.
          nullable: true
          type: string
        isDefault:
          type: boolean
        isSelected:
          type: boolean
        enhancedReporting:
          description: >-
            Account-scoped Enhanced Reporting control for any connected account.
            It is billed at the published per-account rate.
          allOf:
            - $ref: '#/components/schemas/EnhancedReportingAccountControl'
        archivedAt:
          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))$
        createdAt:
          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))$
        updatedAt:
          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))$
        mappedAdvertisers:
          default: []
          description: Advertisers this external account is mapped to for buyer workflows.
          type: array
          items:
            $ref: '#/components/schemas/StorefrontConnectionAccountAdvertiserMapping'
        campaignRollup:
          description: >-
            Directed-campaign rollup for this account. Present only when the
            account has live campaign mirrors and a resolvable currency; omitted
            otherwise.
          allOf:
            - $ref: '#/components/schemas/StorefrontConnectionAccountCampaignRollup'
      required:
        - id
        - connectionId
        - credentialId
        - externalAccountId
        - name
        - advertiser
        - currency
        - effectiveTimezone
        - status
        - providerStatus
        - providerRawStatus
        - accountType
        - amazonSponsoredAds
        - parentExternalId
        - parentName
        - isDefault
        - isSelected
        - enhancedReporting
        - archivedAt
        - createdAt
        - updatedAt
        - mappedAdvertisers
      additionalProperties: false
      description: Provider account discovered for a buyer storefront connection.
    EnhancedReportingAccountControl:
      type: object
      properties:
        eligible:
          type: boolean
        canEnable:
          description: >-
            Whether this currently disabled account can be enabled under the
            active accepted IU Rate Card. An enabled account remains disableable
            if billing authority changes.
          type: boolean
        enabled:
          type: boolean
        activatedAt:
          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))$
        disabledAt:
          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))$
        billingCustomerId:
          nullable: true
          type: integer
          minimum: 0
          exclusiveMinimum: true
          maximum: 9007199254740991
      required:
        - eligible
        - enabled
        - activatedAt
        - disabledAt
        - billingCustomerId
      additionalProperties: false
      description: Account-scoped Enhanced Reporting state and durable activation boundary.
    StorefrontConnectionAccountAdvertiserMapping:
      type: object
      properties:
        linkId:
          type: string
          description: >-
            Identifier of the advertiser-account link row. Pass to DELETE
            /advertisers/{advertiserId}/accounts/{linkId} to unmap.
        sourceId:
          type: string
          description: >-
            Canonical provider ID for an official adapter, or the inventory
            source ID for an external AdCP connection.
        sourceName:
          type: string
          description: Display name for the inventory source.
        agentId:
          type: string
          description: Partner agent ID that receives this mapping.
        advertiserId:
          type: string
          description: Advertiser linked to this discovered provider account.
        advertiserName:
          type: string
          description: Display name for the linked advertiser.
        advertiserPreferredTimezone:
          nullable: true
          description: >-
            The linked advertiser reporting time-zone preference, or null when
            no valid IANA time zone is configured.
          type: string
        unreachableAt:
          default: null
          description: >-
            When set, this mapping is preserved but its platform account is no
            longer reachable through any active connection — relink the platform
            (or re-map the account) to restore it. Unreachable mappings never
            resolve at buy time.
          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))$
        linkedAt:
          nullable: true
          description: When the provider account was first linked.
          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))$
        updatedAt:
          nullable: true
          description: When the provider account mapping was last updated.
          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:
        - linkId
        - sourceId
        - sourceName
        - agentId
        - advertiserId
        - advertiserName
        - advertiserPreferredTimezone
        - unreachableAt
        - linkedAt
        - updatedAt
      additionalProperties: false
      description: >-
        Advertiser mapping for an external account discovered through an
        integration.
    StorefrontConnectionAccountCampaignRollup:
      type: object
      properties:
        campaignsTracked:
          type: integer
          minimum: 0
          maximum: 9007199254740991
          description: >-
            Non-retired tracked campaigns on this account. A tracked campaign is
            a campaign the platform did not set up, mirrored read-only from the
            connected provider account.
        campaignsActive:
          description: >-
            Subset of campaignsTracked whose campaign status is currently
            ACTIVE.
          type: integer
          minimum: 0
          maximum: 9007199254740991
        trackedSpend:
          type: number
          minimum: 0
          description: >-
            Delivered spend across tracked campaigns over the trailing window,
            in the account currency. Provider-reported net — directed buys
            dispatch the full media budget zero-fee, so net equals the buyer's
            budget.
        managedSpend:
          type: number
          minimum: 0
          description: >-
            Delivered spend across managed campaigns (authored through the
            platform) over the trailing window, in the account currency.
            Provider-reported net, same denomination as trackedSpend.
        managedShare:
          nullable: true
          description: >-
            The adoption metric for this relationship: managedSpend /
            (trackedSpend + managedSpend). Null when no spend was accounted in
            the window.
          type: number
          minimum: 0
          maximum: 1
        currency:
          type: string
          pattern: ^[A-Z]{3}$
          description: >-
            ISO 4217 currency all spend values in this rollup are denominated in
            — always the account currency. Rollups are never summed across
            currencies.
        windowDays:
          type: integer
          minimum: 0
          exclusiveMinimum: true
          maximum: 9007199254740991
          description: >-
            Trailing window, in days, the spend aggregates cover (currently
            365).
      required:
        - campaignsTracked
        - campaignsActive
        - trackedSpend
        - managedSpend
        - managedShare
        - currency
        - windowDays
      additionalProperties: false
      description: >-
        Directed-campaign rollup for one connected provider account: tracked =
        mirrored read-only from that account; managed = authored through the
        platform. Spend is provider-reported net in the account currency; sums
        cover delivery denominated in (or reported without) that currency.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key or access token

````