> ## 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 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 Seller Accounts, 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: Asks
    description: >-
      What you are waiting on Scope3 for — support, product, and supply asks in
      one list
  - 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 Seller Accounts
  - name: AI Usage
    description: Seller Account 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
            minimum: 0
            exclusiveMinimum: true
            maximum: 9007199254740991
          description: Filter to one buyer (customer id).
        - in: query
          name: accountRelationshipId
          schema:
            description: >-
              Filter to one seller-owned account relationship. This is the
              authoritative transaction boundary for an External advertiser,
              never a buyer-id heuristic.
            type: string
            pattern: ^[1-9][0-9]*$
          description: >-
            Filter to one seller-owned account relationship. This is the
            authoritative transaction boundary for an External advertiser, never
            a buyer-id heuristic.
        - 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:
            default: 50
            description: Page size (max 200).
            type: integer
            minimum: 0
            exclusiveMinimum: true
            maximum: 200
          description: Page size (max 200).
        - in: query
          name: skip
          schema:
            default: 0
            description: Rows to skip (offset pagination over the sorted list).
            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:
      type: string
      enum:
        - pending_approval
        - forwarding
        - forward_failed
        - awaiting_source
        - rejected
        - canceled
        - booked
        - delivering
        - paused
        - completed
      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.
    StorefrontMediaBuyListResponse:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/StorefrontMediaBuySummary'
        total:
          type: integer
          minimum: 0
          maximum: 9007199254740991
          description: Total rows matching the filters (before pagination).
        warnings:
          type: array
          items:
            type: string
          description: >-
            Non-fatal data-source problems (e.g. an upstream source that could
            not be reached). Empty when every source answered.
        statusFreshness:
          nullable: true
          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).
          type: object
          properties:
            lastConfirmedAt:
              nullable: true
              description: >-
                When statuses were last successfully confirmed with the ad
                platform. Null when no sync has ever succeeded.
              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:
              nullable: true
              description: >-
                Whole hours since the last successful status sync. Null when no
                sync has ever succeeded.
              type: integer
              minimum: 0
              maximum: 9007199254740991
            message:
              type: string
              description: >-
                Seller-facing staleness note, e.g. "status last confirmed 5h ago
                — source unreachable".
          required:
            - lastConfirmedAt
            - hoursSinceConfirmed
            - message
          additionalProperties: false
        delivery:
          nullable: true
          description: >-
            Relationship delivery rollup. Null means none of the matching buys
            has a delivery record, never a zero-valued delivery total.
          type: object
          properties:
            impressions:
              type: number
              minimum: 0
            spend:
              type: number
              minimum: 0
            pacingAgainstBookedBudget:
              nullable: true
              type: number
              minimum: 0
            lastDeliveryDate:
              type: string
              pattern: ^\d{4}-\d{2}-\d{2}$
          required:
            - impressions
            - spend
            - pacingAgainstBookedBudget
            - lastDeliveryDate
          additionalProperties: false
      required:
        - items
        - total
        - warnings
        - statusFreshness
        - delivery
      additionalProperties: false
      description: >-
        Every buy on the storefront — the union of routed and source-managed
        buys — urgency-sorted by default.
    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
    StorefrontMediaBuySummary:
      type: object
      properties:
        mediaBuyId:
          type: string
          description: >-
            The media buy id at this storefront grain (`sf_mb_…` for routed
            buys; the upstream source id for source-managed buys).
        kind:
          type: string
          enum:
            - routed
            - esa
          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).
        buyer:
          type: object
          properties:
            customerId:
              nullable: true
              description: >-
                Buyer customer id (null for upstream source principals with no
                platform customer).
              type: integer
              minimum: -9007199254740991
              maximum: 9007199254740991
            name:
              nullable: true
              description: Buyer display name when known.
              type: string
          required:
            - customerId
            - name
          additionalProperties: false
          description: Who bought it.
        advertiser:
          type: object
          properties:
            name:
              nullable: true
              type: string
          required:
            - name
          additionalProperties: false
          description: >-
            The advertiser/brand named in the seller-visible transaction
            payload, when present.
        operator:
          type: object
          properties:
            name:
              nullable: true
              type: string
          required:
            - name
          additionalProperties: false
          description: >-
            The buying-operator domain recorded on the persisted transaction
            account reference. This is deliberately separate from the advertised
            brand and is null rather than substituted with a buyer-customer
            display name.
        commercial:
          type: object
          properties:
            budget:
              nullable: true
              type: number
              minimum: 0
            currency:
              nullable: true
              type: string
            denomination:
              nullable: true
              description: >-
                `net_media` is the seller-authorized amount after buyer-side
                fees; `source_total` is an upstream source total whose gross/net
                denomination is not declared by that contract.
              type: string
              enum:
                - net_media
                - source_total
            cpm:
              nullable: true
              description: >-
                Seller-visible CPM when the transaction contract supplies enough
                information to derive it; null rather than guessed.
              type: number
              minimum: 0
          required:
            - budget
            - currency
            - denomination
            - cpm
          additionalProperties: false
          description: >-
            Seller-authorized commercial context. Buyer-only gross budget and
            fee details are never exposed here.
        delivery:
          nullable: true
          description: >-
            Delivery for a relationship-scoped buy. Null means the reporting
            pipeline has no delivery record for this buy; it is not a
            zero-valued report.
          type: object
          properties:
            impressions:
              type: number
              minimum: 0
            spend:
              type: number
              minimum: 0
              description: >-
                Seller-reported net spend from the storefront reporting
                pipeline. The pipeline does not provide a delivery currency at
                this projection grain.
            pacingAgainstBookedBudget:
              nullable: true
              description: >-
                Delivered seller-reported spend divided by this buy's
                seller-visible booked budget. Null when no seller-visible booked
                budget is recorded.
              type: number
              minimum: 0
            lastDeliveryDate:
              type: string
              pattern: ^\d{4}-\d{2}-\d{2}$
              description: >-
                Most recent UTC reporting day with a delivery record. This is a
                reporting-day date, not an invented event timestamp.
          required:
            - impressions
            - spend
            - pacingAgainstBookedBudget
            - lastDeliveryDate
          additionalProperties: false
        creative:
          type: object
          properties:
            state:
              nullable: true
              type: string
              enum:
                - pending
                - attached
            attachedCount:
              nullable: true
              type: integer
              minimum: 0
              maximum: 9007199254740991
          required:
            - state
            - attachedCount
          additionalProperties: false
          description: >-
            Creative readiness at list grain. Null means no creative is attached
            or this source contract did not report creative state; attachedCount
            and pendingReason distinguish those cases when known.
        openWork:
          type: object
          properties:
            count:
              type: integer
              minimum: 0
              maximum: 9007199254740991
            actionableCount:
              type: integer
              minimum: 0
              maximum: 9007199254740991
            blockedCount:
              type: integer
              minimum: 0
              maximum: 9007199254740991
            sourceIds:
              type: array
              items:
                type: string
            workItemIds:
              type: array
              items:
                type: string
          required:
            - count
            - actionableCount
            - blockedCount
            - sourceIds
            - workItemIds
          additionalProperties: false
          description: Open modular-source work correlated by this exact media-buy id.
        nextAction:
          type: object
          properties:
            owner:
              type: string
              enum:
                - seller
                - buyer
                - source
                - platform
                - none
            label:
              type: string
          required:
            - owner
            - label
          additionalProperties: false
          description: >-
            The current owner and action. `none` is an explicit no-action state,
            never an omitted inference.
        status:
          $ref: '#/components/schemas/SellerMediaBuyStatus'
        sourceStatus:
          nullable: true
          description: >-
            The raw upstream status as persisted (route leg rollup or source
            status string). Null before anything was sent.
          type: string
        settlementMethod:
          nullable: true
          description: >-
            The settlement method recorded for this booking: interchange means
            Interchange-cleared; seller means seller-cleared. Normal Seller
            Accounts—including third-party sales-agent and Agent-supplied
            (finished-product) sources—are Interchange-cleared today.
            Seller-cleared settlement for Seller Accounts 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.
          type: string
          enum:
            - interchange
            - seller
        pendingReason:
          nullable: true
          description: >-
            Why the buy is not delivering yet (most-blocking leg), when
            derivable. Same vocabulary the buyer sees — one shared enum, never a
            status.
          allOf:
            - $ref: '#/components/schemas/MediaBuyPendingReason'
        pendingSince:
          nullable: true
          description: When the current wait began, when known.
          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:
          nullable: true
          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.
          type: string
        forwardOutcome:
          $ref: '#/components/schemas/SellerForwardOutcome'
        flightStart:
          nullable: true
          description: Flight start ("asap" or ISO 8601) when known.
          type: string
        flightEnd:
          nullable: true
          description: Flight end (ISO 8601) when known.
          type: string
        sourceCount:
          type: integer
          minimum: 0
          maximum: 9007199254740991
          description: >-
            Number of source legs this buy fans out to (1 for source-managed
            buys).
        esaId:
          nullable: true
          description: >-
            Ad server source connection id for source-managed buys; null for
            routed. The wire field remains `esaId` for API compatibility.
          type: string
        createdAt:
          nullable: true
          description: When the buy was received/created, when known.
          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:
          nullable: true
          description: >-
            When the buy was first successfully sent to a source. Null when
            nothing reached a source.
          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
        - advertiser
        - operator
        - commercial
        - delivery
        - creative
        - openWork
        - nextAction
        - status
        - sourceStatus
        - settlementMethod
        - pendingReason
        - pendingSince
        - errorCode
        - forwardOutcome
        - flightStart
        - flightEnd
        - sourceCount
        - esaId
        - createdAt
        - forwardedAt
      additionalProperties: false
      description: One buy on the storefront, at the seller list grain.
    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
    MediaBuyPendingReason:
      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
      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.
    SellerForwardOutcome:
      type: string
      enum:
        - not_forwarded
        - all_completed
        - all_submitted
        - partial
        - failed
      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).
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key or access token

````