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

# Connect CitrusAd

> Connect CitrusAd as an ad server using the standard sponsored-products composition. The connection appears as one inventory source; its internal modules are implementation details. Store credentials separately through the CitrusAd ad-server credential endpoint.



## OpenAPI

````yaml /v2/storefront-api-v2.yaml post /inventory-sources/ad-servers/citrusad
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:
  /inventory-sources/ad-servers/citrusad:
    post:
      tags:
        - Storefront
      summary: Connect CitrusAd
      description: >-
        Connect CitrusAd as an ad server using the standard sponsored-products
        composition. The connection appears as one inventory source; its
        internal modules are implementation details. Store credentials
        separately through the CitrusAd ad-server credential endpoint.
      operationId: connectCitrusAdAdServer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCitrusAdModularSourceBody'
      responses:
        '201':
          description: Connect CitrusAd
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CitrusAdModularSourceResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - bearerAuth: []
components:
  schemas:
    CreateCitrusAdModularSourceBody:
      description: >-
        Connects CitrusAd using the standard sponsored-products composition. API
        credentials are stored separately through the CitrusAd ad-server
        credential endpoint.
      type: object
      properties:
        sourceId:
          type: string
          minLength: 1
          maxLength: 255
          pattern: ^[a-z0-9][a-z0-9_-]*$
        name:
          type: string
          minLength: 1
          maxLength: 255
        environment:
          type: string
          enum:
            - sandbox
            - production
        teamId:
          type: string
          minLength: 1
          maxLength: 255
        namespaces:
          minItems: 1
          type: array
          items:
            type: object
            properties:
              namespace:
                type: string
                minLength: 1
                maxLength: 255
              retailerName:
                type: string
                minLength: 1
                maxLength: 255
              publisherDomain:
                type: string
                maxLength: 253
                pattern: >-
                  ^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$
            required:
              - namespace
              - retailerName
              - publisherDomain
        defaultCurrency:
          type: string
          pattern: ^[A-Za-z]{3}$
        floorPrice:
          type: number
          minimum: 0
      required:
        - environment
        - teamId
        - namespaces
        - defaultCurrency
    CitrusAdModularSourceResponse:
      description: >-
        Seller-facing CitrusAd ad-server connection. Internal recipe modules are
        intentionally not exposed.
      type: object
      properties:
        inventorySourceId:
          type: string
        sourceId:
          type: string
        provider:
          type: string
          enum:
            - citrusad
        connectionType:
          type: string
          enum:
            - AD_SERVER
        status:
          type: string
          enum:
            - CONFIGURING
        credentialRequired:
          type: boolean
          enum:
            - true
        supportedFormatIds:
          type: array
          items:
            type: string
            enum:
              - citrusad_sponsored_product
      required:
        - inventorySourceId
        - sourceId
        - provider
        - connectionType
        - status
        - credentialRequired
        - supportedFormatIds
      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
    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
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key or access token

````