> ## 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 everything waiting on someone

> The union of pending media-buy approvals, pending creative reviews, failed forwards (grouped by structured error code, each carrying the recovery-class-gated action: retry, fix-and-resubmit, or escalate), and buys awaiting asynchronous source acceptance ("waiting on source moderation since T"). Groups appear only when non-empty.



## OpenAPI

````yaml /v2/storefront-api-v2.yaml get /pending-operations
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:
  /pending-operations:
    get:
      tags:
        - Storefront
      summary: List everything waiting on someone
      description: >-
        The union of pending media-buy approvals, pending creative reviews,
        failed forwards (grouped by structured error code, each carrying the
        recovery-class-gated action: retry, fix-and-resubmit, or escalate), and
        buys awaiting asynchronous source acceptance ("waiting on source
        moderation since T"). Groups appear only when non-empty.
      operationId: getStorefrontPendingOperations
      parameters:
        - in: query
          name: manualWorkTake
          schema:
            default: 200
            type: integer
            minimum: 0
            exclusiveMinimum: true
            maximum: 200
        - in: query
          name: manualWorkSkip
          schema:
            default: 0
            type: integer
            minimum: 0
            maximum: 9007199254740991
      responses:
        '200':
          description: List everything waiting on someone
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StorefrontPendingOperationsResponse'
        '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:
    StorefrontPendingOperationsResponse:
      type: object
      properties:
        approvals:
          description: Media buys waiting on operator approval.
          type: object
          properties:
            count:
              type: integer
              minimum: 0
              exclusiveMinimum: true
              maximum: 9007199254740991
            items:
              type: array
              items:
                $ref: '#/components/schemas/PendingOperationsApprovalItem'
          required:
            - count
            - items
          additionalProperties: false
        creativeReviews:
          description: Creatives waiting on operator review.
          type: object
          properties:
            count:
              type: integer
              minimum: 0
              exclusiveMinimum: true
              maximum: 9007199254740991
            items:
              type: array
              items:
                $ref: '#/components/schemas/PendingOperationsCreativeReviewItem'
          required:
            - count
            - items
          additionalProperties: false
        failedForwards:
          description: >-
            Forwards that failed, grouped by structured error code with the
            recovery-class-gated action.
          type: object
          properties:
            count:
              type: integer
              minimum: 0
              exclusiveMinimum: true
              maximum: 9007199254740991
            groups:
              type: array
              items:
                $ref: '#/components/schemas/PendingOperationsFailedForwardGroup'
          required:
            - count
            - groups
          additionalProperties: false
        awaitingSource:
          description: >-
            Buys a source accepted asynchronously and is still moderating
            ("waiting on source moderation since T").
          type: object
          properties:
            count:
              type: integer
              minimum: 0
              exclusiveMinimum: true
              maximum: 9007199254740991
            items:
              type: array
              items:
                $ref: '#/components/schemas/PendingOperationsAwaitingSourceItem'
          required:
            - count
            - items
          additionalProperties: false
        manualSourceWork:
          description: >-
            Open modular-source booking, creative-sync, and final-reporting
            work, grouped by the same buyer/media-buy/source identifiers and
            owned by the seller. `count` and `mediaBuyCount` cover the full
            active backlog; `returnedCount`, `offset`, `nextOffset`, and
            `truncated` describe the bounded page and how to continue it.
          type: object
          properties:
            count:
              type: integer
              minimum: 0
              exclusiveMinimum: true
              maximum: 9007199254740991
            returnedCount:
              type: integer
              minimum: 0
              exclusiveMinimum: true
              maximum: 9007199254740991
            mediaBuyCount:
              type: integer
              minimum: 0
              exclusiveMinimum: true
              maximum: 9007199254740991
            truncated:
              type: boolean
            offset:
              type: integer
              minimum: 0
              maximum: 9007199254740991
            nextOffset:
              nullable: true
              type: integer
              minimum: 0
              exclusiveMinimum: true
              maximum: 9007199254740991
            groups:
              minItems: 1
              type: array
              items:
                $ref: '#/components/schemas/PendingOperationsManualSourceWorkGroup'
          required:
            - count
            - returnedCount
            - mediaBuyCount
            - truncated
            - offset
            - nextOffset
            - groups
          additionalProperties: false
        sourceDegradations:
          description: >-
            Seller-owned source-health diagnoses (a degraded ad-server or
            sales-agent source) surfaced here so they are visible without
            opening the source directly. Scope3/vendor-owned diagnoses never
            appear.
          type: object
          properties:
            count:
              type: integer
              minimum: 0
              exclusiveMinimum: true
              maximum: 9007199254740991
            items:
              type: array
              items:
                $ref: '#/components/schemas/PendingOperationsSourceDegradationItem'
          required:
            - count
            - items
          additionalProperties: false
        gamCleanups:
          description: >-
            Unresolved safe GAM failed-order cleanup operations. Archive is
            offered only after verified upstream safety and explicit
            confirmation.
          type: object
          properties:
            count:
              type: integer
              minimum: 0
              exclusiveMinimum: true
              maximum: 9007199254740991
            items:
              type: array
              items:
                type: object
                properties:
                  operationId:
                    type: string
                  orderId:
                    type: string
                  sourceId:
                    type: string
                  sourceName:
                    nullable: true
                    type: string
                  outcome:
                    type: string
                    enum:
                      - failed
                      - refused
                  safeToCleanup:
                    type: boolean
                  requiredPermission:
                    nullable: true
                    type: string
                  retryDisposition:
                    type: string
                    enum:
                      - not_applicable
                      - retryable
                      - user_action_required
                      - manual_review_required
                  safeNextAction:
                    type: string
                    enum:
                      - none
                      - retry_cleanup
                      - grant_archive_orders_and_recheck
                      - reauthenticate_and_recheck
                      - clean_up_manually_in_gam
                      - review_order_in_gam
                  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))$
                required:
                  - operationId
                  - orderId
                  - sourceId
                  - sourceName
                  - outcome
                  - safeToCleanup
                  - requiredPermission
                  - retryDisposition
                  - safeNextAction
                  - createdAt
                additionalProperties: false
          required:
            - count
            - items
          additionalProperties: false
      additionalProperties: false
      description: >-
        The union of things waiting on someone: pending approvals, pending
        creative reviews, failed forwards (grouped by error code), async-pending
        source acceptance, modular manual source work, and seller-owned source
        degradations. Groups appear only when non-empty.
    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
    PendingOperationsApprovalItem:
      type: object
      properties:
        mediaBuyId:
          type: string
        kind:
          type: string
          enum:
            - create
            - update
        buyer:
          type: object
          properties:
            customerId:
              nullable: true
              type: integer
              minimum: -9007199254740991
              maximum: 9007199254740991
            name:
              nullable: true
              type: string
          required:
            - customerId
            - name
          additionalProperties: false
        submittedAt:
          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
        - submittedAt
      additionalProperties: false
      description: One media buy waiting on operator approval.
    PendingOperationsCreativeReviewItem:
      type: object
      properties:
        creativeId:
          type: string
        reviewRef:
          type: string
          pattern: ^review:[1-9]\d*$
          description: Collision-free reference for this exact creative review.
        mediaBuyId:
          nullable: true
          type: string
        buyer:
          type: object
          properties:
            customerId:
              nullable: true
              type: integer
              minimum: -9007199254740991
              maximum: 9007199254740991
            name:
              nullable: true
              type: string
          required:
            - customerId
            - name
          additionalProperties: false
        submittedAt:
          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:
        - creativeId
        - reviewRef
        - mediaBuyId
        - buyer
        - submittedAt
      additionalProperties: false
      description: One creative waiting on operator review.
    PendingOperationsFailedForwardGroup:
      type: object
      properties:
        errorCode:
          type: string
          description: >-
            Structured error code the group shares — a source outage reads as
            ONE row, not N.
        recovery:
          nullable: true
          type: string
          enum:
            - transient
            - correctable
            - structural
        action:
          description: The action class for every item in this group.
          allOf:
            - $ref: '#/components/schemas/SellerRecoveryAction'
        count:
          type: integer
          minimum: 0
          exclusiveMinimum: true
          maximum: 9007199254740991
        items:
          type: array
          items:
            $ref: '#/components/schemas/PendingOperationsFailedForwardItem'
      required:
        - errorCode
        - recovery
        - action
        - count
        - items
      additionalProperties: false
      description: Failed forwards grouped by structured error code.
    PendingOperationsAwaitingSourceItem:
      type: object
      properties:
        mediaBuyId:
          type: string
        sourceId:
          type: string
        sourceName:
          nullable: true
          type: string
        buyer:
          type: object
          properties:
            customerId:
              nullable: true
              type: integer
              minimum: -9007199254740991
              maximum: 9007199254740991
            name:
              nullable: true
              type: string
          required:
            - customerId
            - name
          additionalProperties: false
        since:
          nullable: true
          description: Waiting on source moderation since 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))$
        taskId:
          nullable: true
          description: The source's task id for the pending acceptance — their reference.
          type: string
      required:
        - mediaBuyId
        - sourceId
        - sourceName
        - buyer
        - since
        - taskId
      additionalProperties: false
      description: One buy the source accepted asynchronously and is still moderating.
    PendingOperationsManualSourceWorkGroup:
      type: object
      properties:
        mediaBuyId:
          type: string
        buyerCustomerId:
          nullable: true
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        sourceId:
          type: string
        sourceName:
          nullable: true
          type: string
        buyer:
          type: object
          properties:
            customerId:
              nullable: true
              type: integer
              minimum: -9007199254740991
              maximum: 9007199254740991
            name:
              nullable: true
              type: string
          required:
            - customerId
            - name
          additionalProperties: false
        items:
          minItems: 1
          type: array
          items:
            $ref: '#/components/schemas/PendingOperationsManualSourceWorkItem'
      required:
        - mediaBuyId
        - buyerCustomerId
        - sourceId
        - sourceName
        - buyer
        - items
      additionalProperties: false
      description: >-
        Manual booking, creative-sync, and final-reporting work grouped by the
        same buyer/media-buy/source boundary.
    PendingOperationsSourceDegradationItem:
      type: object
      properties:
        sourceId:
          nullable: true
          type: string
        sourceName:
          type: string
        severity:
          type: string
          enum:
            - blocking
            - attention
            - advisory
        headline:
          type: string
          description: >-
            Customer-safe, one sentence: what is wrong and why it matters to the
            seller.
      required:
        - sourceId
        - sourceName
        - severity
        - headline
      additionalProperties: false
      description: >-
        One seller-owned source-health diagnosis
        (docs/spec/storefront/source-diagnosis-projection.md) — a projection of
        the same diagnoses array the readiness checklist and the ad-server
        widget already render.
    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
    SellerRecoveryAction:
      type: string
      enum:
        - retry
        - force_retry
        - fix_and_resubmit
        - escalate
      description: >-
        Which action class applies: retry (transient failure, not terminalized —
        the platform can re-attempt), force_retry (a source refused the buy and
        the platform terminalized it, but every leg is a failed unsent one, so
        an operator can re-send it in place with `forceTerminal`),
        fix_and_resubmit (correctable input), escalate (nothing the operator can
        re-send — including a buy terminalized before any source was contacted;
        escalate to Scope3 with the references attached).
    PendingOperationsFailedForwardItem:
      type: object
      properties:
        mediaBuyId:
          type: string
        buyer:
          type: object
          properties:
            customerId:
              nullable: true
              type: integer
              minimum: -9007199254740991
              maximum: 9007199254740991
            name:
              nullable: true
              type: string
          required:
            - customerId
            - name
          additionalProperties: false
        since:
          nullable: true
          description: When the failure was recorded.
          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))$
        terminalized:
          type: boolean
          description: >-
            True when the platform has stopped retrying this buy (structural
            failure or retry window lapsed).
        action:
          $ref: '#/components/schemas/SellerRecoveryAction'
        references:
          type: object
          properties:
            idempotencyKey:
              nullable: true
              type: string
            requestedAt:
              nullable: true
              type: string
          required:
            - idempotencyKey
            - requestedAt
          additionalProperties: false
          description: >-
            Pre-attached references for an escalation: the create idempotency
            key and request timestamp.
      required:
        - mediaBuyId
        - buyer
        - since
        - terminalized
        - action
        - references
      additionalProperties: false
      description: One buy whose forward failed, with its gated action.
    PendingOperationsManualSourceWorkItem:
      type: object
      properties:
        workItemId:
          type: string
        mediaBuyId:
          type: string
        buyerCustomerId:
          nullable: true
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        sourceId:
          type: string
        sourceName:
          nullable: true
          type: string
        buyer:
          type: object
          properties:
            customerId:
              nullable: true
              type: integer
              minimum: -9007199254740991
              maximum: 9007199254740991
            name:
              nullable: true
              type: string
          required:
            - customerId
            - name
          additionalProperties: false
        kind:
          type: string
          enum:
            - EXECUTE_UPSTREAM_BOOKING
            - SYNC_UPSTREAM_CREATIVE
            - UPLOAD_FINAL_REPORT
        title:
          type: string
        status:
          type: string
          enum:
            - OPEN
            - IN_PROGRESS
            - BLOCKED
        actionState:
          type: string
          enum:
            - action_required
            - in_progress
            - blocked
        currentAction:
          type: string
        blockedReason:
          nullable: true
          type: string
        priority:
          type: string
          enum:
            - LOW
            - NORMAL
            - HIGH
            - URGENT
        dueAt:
          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))$
        nextOwner:
          type: string
          enum:
            - seller
        action:
          type: object
          properties:
            operation:
              type: string
              enum:
                - get_modular_inventory_source_readiness
            arguments:
              type: object
              properties:
                sourceId:
                  type: string
                workItemId:
                  type: string
              required:
                - sourceId
                - workItemId
              additionalProperties: false
          required:
            - operation
            - arguments
          additionalProperties: false
      required:
        - workItemId
        - mediaBuyId
        - buyerCustomerId
        - sourceId
        - sourceName
        - buyer
        - kind
        - title
        - status
        - actionState
        - currentAction
        - blockedReason
        - priority
        - dueAt
        - createdAt
        - nextOwner
        - action
      additionalProperties: false
      description: >-
        One seller-owned modular-source task, correlated to the exact
        buyer/media-buy/source identity and deep-linked to its exact source work
        item.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key or access token

````