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

# List every media buy on the storefront

> The union of routed buys (approval queue + per-source forwarding routes) and ESA-managed buys, with status filters. Default sort is urgency: buys still waiting on someone whose flight starts within 48 hours come first. Each row carries the shared `pendingReason` vocabulary (the same enum buyers see), the latest structured error code, and the forward outcome.



## OpenAPI

````yaml /v2/storefront-api-v2.yaml get /media-buys
openapi: 3.0.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
security: []
tags:
  - name: Account
    description: Account management, service tokens, and preferences
  - name: Storefront
    description: Manage storefront and inventory sources
  - name: Storefront Agents
    description: List and manage registered sales, signals, and outcomes agents
  - name: Storefront Activity
    description: Audit log of configuration and inventory changes on the storefront
  - name: Storefront Billing
    description: Payout bank details and billing configuration for storefronts
  - name: AI Usage
    description: Storefront AI token usage visibility by model
  - name: MCP
    description: Model Context Protocol endpoints
paths:
  /media-buys:
    get:
      tags:
        - Storefront
      summary: List every media buy on the storefront
      description: >-
        The union of routed buys (approval queue + per-source forwarding routes)
        and ESA-managed buys, with status filters. Default sort is urgency: buys
        still waiting on someone whose flight starts within 48 hours come first.
        Each row carries the shared `pendingReason` vocabulary (the same enum
        buyers see), the latest structured error code, and the forward outcome.
      operationId: listStorefrontMediaBuys
      parameters:
        - in: query
          name: status
          schema:
            description: Filter to one seller lifecycle state.
            allOf:
              - $ref: '#/components/schemas/SellerMediaBuyStatus'
          description: Filter to one seller lifecycle state.
        - in: query
          name: buyerCustomerId
          schema:
            description: Filter to one buyer (customer id).
            type: integer
            maximum: 9007199254740991
            minimum: 1
          description: Filter to one buyer (customer id).
        - in: query
          name: sourceId
          schema:
            description: >-
              Filter to buys with a leg on this inventory source (routed buys)
              or managed by this ad server source.
            type: string
            minLength: 1
          description: >-
            Filter to buys with a leg on this inventory source (routed buys) or
            managed by this ad server source.
        - in: query
          name: flightStartFrom
          schema:
            description: Only buys whose flight starts at/after this instant.
            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))$
          description: Only buys whose flight starts at/after this instant.
        - in: query
          name: flightStartTo
          schema:
            description: Only buys whose flight starts at/before this instant.
            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))$
          description: Only buys whose flight starts at/before this instant.
        - in: query
          name: take
          schema:
            description: Page size (max 200).
            default: 50
            type: integer
            maximum: 200
            minimum: 1
          description: Page size (max 200).
        - in: query
          name: skip
          schema:
            description: Rows to skip (offset pagination over the sorted list).
            default: 0
            type: integer
            minimum: 0
            maximum: 9007199254740991
          description: Rows to skip (offset pagination over the sorted list).
      responses:
        '200':
          description: List every media buy on the storefront
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StorefrontMediaBuyListResponse'
        '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: No storefront exists for the calling operator.
          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:
    SellerMediaBuyStatus:
      description: >-
        Coarse seller-facing lifecycle of a buy on the storefront, derived from
        persisted approval + forwarding state. A platform list-view convenience
        — not an AdCP MediaBuyStatus. Use the per-buy timeline for the exact
        underlying states.
      type: string
      enum:
        - pending_approval
        - forwarding
        - forward_failed
        - awaiting_source
        - rejected
        - canceled
        - booked
        - delivering
        - paused
        - completed
    StorefrontMediaBuyListResponse:
      description: >-
        Every buy on the storefront — the union of routed and source-managed
        buys — urgency-sorted by default.
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/StorefrontMediaBuySummary'
        total:
          description: Total rows matching the filters (before pagination).
          type: integer
          minimum: 0
          maximum: 9007199254740991
        warnings:
          description: >-
            Non-fatal data-source problems (e.g. an upstream source that could
            not be reached). Empty when every source answered.
          type: array
          items:
            type: string
        statusFreshness:
          description: >-
            Non-null when this storefront routes buys through an ad-platform
            connection whose status sync has been failing long enough that
            displayed statuses may be out of date. Null when statuses are
            current (or the storefront has no such connection).
          nullable: true
          type: object
          properties:
            lastConfirmedAt:
              description: >-
                When statuses were last successfully confirmed with the ad
                platform. Null when no sync has ever succeeded.
              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))$
            hoursSinceConfirmed:
              description: >-
                Whole hours since the last successful status sync. Null when no
                sync has ever succeeded.
              nullable: true
              type: integer
              minimum: 0
              maximum: 9007199254740991
            message:
              description: >-
                Seller-facing staleness note, e.g. "status last confirmed 5h ago
                — source unreachable".
              type: string
          required:
            - lastConfirmedAt
            - hoursSinceConfirmed
            - message
          additionalProperties: false
      required:
        - items
        - total
        - warnings
        - statusFreshness
      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
    StorefrontMediaBuySummary:
      description: One buy on the storefront, at the seller list grain.
      type: object
      properties:
        mediaBuyId:
          description: >-
            The media buy id at this storefront grain (`sf_mb_…` for routed
            buys; the upstream source id for source-managed buys).
          type: string
        kind:
          description: >-
            Where this buy is managed: `routed` = forwarded through the
            storefront routing layer (approval queue + per-source routes); `esa`
            = managed by an ad server source upstream (`esa` is the stable wire
            value).
          type: string
          enum:
            - routed
            - esa
        buyer:
          description: Who bought it.
          type: object
          properties:
            customerId:
              description: >-
                Buyer customer id (null for upstream source principals with no
                platform customer).
              nullable: true
              type: integer
              minimum: -9007199254740991
              maximum: 9007199254740991
            name:
              description: Buyer display name when known.
              nullable: true
              type: string
          required:
            - customerId
            - name
          additionalProperties: false
        status:
          $ref: '#/components/schemas/SellerMediaBuyStatus'
        sourceStatus:
          description: >-
            The raw upstream status as persisted (route leg rollup or source
            status string). Null before anything was sent.
          nullable: true
          type: string
        settlementMethod:
          description: >-
            The settlement method recorded for this booking: interchange means
            Interchange-cleared; seller means seller-cleared. Normal
            storefronts—including third-party sales-agent and
            finished-product/pass-through sources—are Interchange-cleared today.
            Seller-cleared storefront settlement is not yet configurable; seller
            currently appears only for official sales-adapter buys already
            settled under a downstream platform agreement. Null only for
            historical or upstream rows whose method was not recorded.
          nullable: true
          type: string
          enum:
            - interchange
            - seller
        pendingReason:
          description: >-
            Why the buy is not delivering yet (most-blocking leg), when
            derivable. Same vocabulary the buyer sees — one shared enum, never a
            status.
          nullable: true
          allOf:
            - $ref: '#/components/schemas/MediaBuyPendingReason'
        pendingSince:
          description: When the current wait began, when known.
          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))$
        errorCode:
          description: >-
            Structured error code of the latest failed exchange for this buy
            (ledger vocabulary, e.g. `unknown_product_ids`). Null when the
            latest exchange did not fail.
          nullable: true
          type: string
        forwardOutcome:
          $ref: '#/components/schemas/SellerForwardOutcome'
        flightStart:
          description: Flight start ("asap" or ISO 8601) when known.
          nullable: true
          type: string
        flightEnd:
          description: Flight end (ISO 8601) when known.
          nullable: true
          type: string
        sourceCount:
          description: >-
            Number of source legs this buy fans out to (1 for source-managed
            buys).
          type: integer
          minimum: 0
          maximum: 9007199254740991
        esaId:
          description: >-
            Ad server source connection id for source-managed buys; null for
            routed. The wire field remains `esaId` for API compatibility.
          nullable: true
          type: string
        createdAt:
          description: When the buy was received/created, when known.
          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))$
        forwardedAt:
          description: >-
            When the buy was first successfully sent to a source. Null when
            nothing reached a source.
          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:
        - mediaBuyId
        - kind
        - buyer
        - status
        - sourceStatus
        - settlementMethod
        - pendingReason
        - pendingSince
        - errorCode
        - forwardOutcome
        - flightStart
        - flightEnd
        - sourceCount
        - esaId
        - createdAt
        - forwardedAt
      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
    MediaBuyPendingReason:
      description: >-
        Why a not-yet-delivering media buy is waiting, and implicitly whose side
        owns the wait. A platform-derived annotation — never a status value.
        awaiting_storefront_approval / awaiting_source_moderation /
        creative_processing_at_source / awaiting_creative_approval = the seller
        side owns the wait; no_creatives_attached / source_rejected_creatives =
        the buyer owns it (attach or fix creatives); forward_failed_retrying /
        forward_failed_needs_correction = the platform owns it;
        accepted_awaiting_trafficking / scheduled_not_started = nothing is
        wrong, the buy is queued or scheduled.
      type: string
      enum:
        - forward_failed_needs_correction
        - forward_failed_retrying
        - awaiting_storefront_approval
        - awaiting_source_moderation
        - no_creatives_attached
        - source_rejected_creatives
        - creative_processing_at_source
        - awaiting_creative_approval
        - accepted_awaiting_trafficking
        - scheduled_not_started
    SellerForwardOutcome:
      description: >-
        How far forwarding to the underlying source(s) got: not_forwarded
        (nothing dispatched yet), all_completed (every source accepted inline),
        all_submitted (every source accepted asynchronously and is still
        finishing acceptance), partial (some sources accepted, some did not),
        failed (dispatch attempted, no source accepted).
      type: string
      enum:
        - not_forwarded
        - all_completed
        - all_submitted
        - partial
        - failed
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key or access token

````