openapi: 3.0.3
info:
  title: ScanSource Product API
  description: The ScanSource Product API provides real-time product information, pricing, and availability for technology distribution partners. Supports single and batch item queries for inventory checks, pricing lookups, and product search.
  version: 1.0.0
  contact:
    name: ScanSource Partner Support
    email: B2BRequest@scansource.com
    url: https://partnerportal.scansource.com
  x-logo:
    url: https://www.scansource.com/logo.png
servers:
- url: https://services.scansource.com/api
  description: ScanSource Production API
tags:
- name: Products
  description: Product information, search, and catalog operations
- name: Pricing
  description: Real-time pricing lookups for partner customers
- name: Availability
  description: Real-time inventory availability checks
paths:
  /product/search:
    get:
      operationId: searchProducts
      summary: Search Products
      description: Search for products in the ScanSource catalog using filters such as manufacturer, category, and keyword text. Returns paginated results.
      tags:
      - Products
      parameters:
      - name: customerNumber
        in: query
        required: true
        description: Customer account number for the requesting partner
        schema:
          type: string
      - name: itemNumber
        in: query
        required: false
        description: Specific item number to search for
        schema:
          type: string
      - name: partNumberType
        in: query
        required: false
        description: Type of part number (manufacturer, vendor, etc.)
        schema:
          type: string
      - name: manufacturer
        in: query
        required: false
        description: Filter by manufacturer name
        schema:
          type: string
      - name: catalogName
        in: query
        required: false
        description: Filter by catalog name
        schema:
          type: string
      - name: categoryPath
        in: query
        required: false
        description: Filter by category path
        schema:
          type: string
      - name: includeObsolete
        in: query
        required: false
        description: Include discontinued/obsolete products in results
        schema:
          type: boolean
      - name: searchText
        in: query
        required: false
        description: Free-text search string
        schema:
          type: string
      - name: useAndOperator
        in: query
        required: false
        description: Use AND operator between search terms (vs OR)
        schema:
          type: boolean
      - name: region
        in: query
        required: false
        description: Geographic region for the search
        schema:
          type: string
      - name: page
        in: query
        required: false
        description: Page number for pagination
        schema:
          type: integer
          default: 1
      - name: pageSize
        in: query
        required: false
        description: Number of results per page
        schema:
          type: integer
          default: 20
          maximum: 100
      responses:
        '200':
          description: Successful product search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductSearchResponse'
        '400':
          description: Bad request - invalid parameters
        '401':
          description: Unauthorized - invalid subscription key
        '403':
          description: Forbidden - invalid customer number
      security:
      - ApiKeyAuth: []
  /product/detail:
    get:
      operationId: getProductDetail
      summary: Get Product Detail
      description: Retrieve detailed product information including specifications, dimensions, weight, and other attributes for a specific item.
      tags:
      - Products
      parameters:
      - name: customerNumber
        in: query
        required: true
        description: Customer account number for the requesting partner
        schema:
          type: string
      - name: itemNumber
        in: query
        required: true
        description: Item number to retrieve details for
        schema:
          type: string
      - name: partNumberType
        in: query
        required: false
        description: Type of part number provided
        schema:
          type: string
      - name: region
        in: query
        required: false
        description: Geographic region for pricing
        schema:
          type: string
      responses:
        '200':
          description: Successful product detail response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductDetail'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '404':
          description: Product not found
      security:
      - ApiKeyAuth: []
  /product/pricing:
    post:
      operationId: getProductPricing
      summary: Get Product Pricing
      description: Retrieve real-time pricing for one or more products for a specific customer. Recommended batch size is a maximum of 40 items per request.
      tags:
      - Pricing
      parameters:
      - name: customerNumber
        in: query
        required: true
        description: Customer account number for pricing context
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PricingRequest'
      responses:
        '200':
          description: Successful pricing response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PricingResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
      security:
      - ApiKeyAuth: []
  /product/availability:
    post:
      operationId: getProductAvailability
      summary: Get Product Availability
      description: Check real-time inventory availability for one or more products. Recommended batch size is a maximum of 40 items per request. Used at point-of-demand to avoid unnecessary bulk downloads.
      tags:
      - Availability
      parameters:
      - name: customerNumber
        in: query
        required: false
        description: Customer account number
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AvailabilityRequest'
      responses:
        '200':
          description: Successful availability response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AvailabilityResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
      security:
      - ApiKeyAuth: []
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Ocp-Apim-Subscription-Key
      description: Azure API Management subscription key obtained from the ScanSource partner portal
  schemas:
    ProductSearchResponse:
      type: object
      properties:
        totalCount:
          type: integer
          description: Total number of matching products
        page:
          type: integer
          description: Current page number
        pageSize:
          type: integer
          description: Number of results per page
        items:
          type: array
          items:
            $ref: '#/components/schemas/ProductSummary'
    ProductSummary:
      type: object
      properties:
        itemNumber:
          type: string
          description: ScanSource item number
        manufacturerPartNumber:
          type: string
          description: Manufacturer part number
        manufacturer:
          type: string
          description: Manufacturer name
        description:
          type: string
          description: Product description
        categoryPath:
          type: string
          description: Product category path
        isObsolete:
          type: boolean
          description: Whether the product is discontinued
    ProductDetail:
      type: object
      properties:
        itemNumber:
          type: string
          description: ScanSource item number
        manufacturerPartNumber:
          type: string
          description: Manufacturer part number
        manufacturer:
          type: string
          description: Manufacturer name
        description:
          type: string
          description: Detailed product description
        specifications:
          type: object
          description: Product technical specifications
          additionalProperties:
            type: string
        weight:
          type: number
          description: Product weight in pounds
        dimensions:
          type: object
          properties:
            length:
              type: number
            width:
              type: number
            height:
              type: number
        categoryPath:
          type: string
          description: Product category hierarchy
        upc:
          type: string
          description: Universal Product Code
        isObsolete:
          type: boolean
          description: Whether the product has been discontinued
    PricingRequest:
      type: object
      required:
      - items
      properties:
        items:
          type: array
          maxItems: 40
          description: List of items to price (max 40 per request)
          items:
            type: object
            required:
            - itemNumber
            properties:
              itemNumber:
                type: string
                description: ScanSource or manufacturer item number
              partNumberType:
                type: string
                description: Type of the item number
              quantity:
                type: integer
                description: Quantity for pricing
        warehouse:
          type: string
          description: Preferred warehouse code
        businessUnit:
          type: string
          description: Business unit for pricing context
    PricingResponse:
      type: object
      properties:
        items:
          type: array
          items:
            type: object
            properties:
              itemNumber:
                type: string
              manufacturerPartNumber:
                type: string
              unitPrice:
                type: number
                format: float
              currency:
                type: string
              priceBreaks:
                type: array
                items:
                  type: object
                  properties:
                    quantity:
                      type: integer
                    price:
                      type: number
    AvailabilityRequest:
      type: object
      required:
      - items
      properties:
        items:
          type: array
          maxItems: 40
          description: List of items to check availability for (max 40 per request)
          items:
            type: object
            required:
            - itemNumber
            properties:
              itemNumber:
                type: string
                description: ScanSource or manufacturer item number
              partNumberType:
                type: string
                description: Type of the item number
              quantity:
                type: integer
                description: Quantity needed
        warehouse:
          type: string
          description: Preferred warehouse code
        businessUnit:
          type: string
          description: Business unit code
    AvailabilityResponse:
      type: object
      properties:
        items:
          type: array
          items:
            type: object
            properties:
              itemNumber:
                type: string
              manufacturerPartNumber:
                type: string
              quantityAvailable:
                type: integer
                description: Quantity currently in stock
              warehouse:
                type: string
                description: Warehouse with available stock
              estimatedShipDate:
                type: string
                format: date
                description: Estimated shipping date if not immediately available