openapi: 3.0.3
info:
  title: ScanSource Sales Order API
  description: The ScanSource Sales Order API enables technology distribution partners to create, track, and manage purchase orders programmatically. Supports synchronous and asynchronous order creation, order status queries, shipping quotes, VRD operations, order cancellation, and serial number tracking.
  version: 1.0.0
  contact:
    name: ScanSource Partner Support
    email: B2BRequest@scansource.com
    url: https://partnerportal.scansource.com
servers:
- url: https://services.scansource.com/api
  description: ScanSource Production API
tags:
- name: Orders
  description: Sales order creation and management
- name: Tracking
  description: Order tracking and delivery information
- name: Shipping
  description: Shipping quotes and logistics
paths:
  /salesorder/create:
    post:
      operationId: createSalesOrder
      summary: Create Sales Order
      description: Create a new synchronous sales order in ScanSource. Returns the order confirmation upon completion. Recommended for testing in sandbox before production use.
      tags:
      - Orders
      parameters:
      - name: customerNumber
        in: query
        required: true
        description: Customer account number
        schema:
          type: string
      - name: requestor
        in: query
        required: false
        description: Identifier of the requestor
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SalesOrderRequest'
      responses:
        '200':
          description: Order successfully created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SalesOrderResponse'
        '400':
          description: Bad request - invalid order data
        '401':
          description: Unauthorized
      security:
      - ApiKeyAuth: []
  /salesorder/createAsync:
    post:
      operationId: createSalesOrderAsync
      summary: Create Sales Order Async
      description: Create a new asynchronous sales order. Returns immediately with a reference and processes the order in the background. Use for high-volume or non-blocking integrations.
      tags:
      - Orders
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SalesOrderRequest'
      responses:
        '202':
          description: Order accepted for async processing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncOrderResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
      security:
      - ApiKeyAuth: []
  /salesorder/vrd:
    post:
      operationId: createVrdOrder
      summary: Create VRD Order
      description: Create a Virtual Return Distribution (VRD) order for managing product returns through ScanSource.
      tags:
      - Orders
      parameters:
      - name: customerNumber
        in: query
        required: true
        description: Customer account number
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: VRD order created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SalesOrderResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
      security:
      - ApiKeyAuth: []
  /salesorder/summary/{customerNumber}:
    get:
      operationId: getSalesOrderSummary
      summary: Get Sales Order Summary
      description: Retrieve a paginated summary view of sales orders for a customer. Supports filtering by date range, sales order number, invoice number, and purchase order number.
      tags:
      - Orders
      parameters:
      - name: customerNumber
        in: path
        required: true
        description: Customer account number
        schema:
          type: string
      - name: page
        in: query
        required: false
        description: Page number
        schema:
          type: integer
          default: 1
      - name: pageSize
        in: query
        required: false
        description: Results per page
        schema:
          type: integer
          default: 20
      - name: salesOrderNumber
        in: query
        required: false
        description: Filter by ScanSource sales order number
        schema:
          type: string
      - name: invoiceNumber
        in: query
        required: false
        description: Filter by invoice number
        schema:
          type: string
      - name: poNumber
        in: query
        required: false
        description: Filter by customer purchase order number
        schema:
          type: string
      - name: fromDate
        in: query
        required: false
        description: Start date filter (ISO 8601)
        schema:
          type: string
          format: date
      - name: toDate
        in: query
        required: false
        description: End date filter (ISO 8601)
        schema:
          type: string
          format: date
      responses:
        '200':
          description: Order summary results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderSummaryResponse'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden - invalid customer
      security:
      - ApiKeyAuth: []
  /salesorder/list/{customerNumber}:
    get:
      operationId: listSalesOrders
      summary: List Sales Orders
      description: Retrieve a detailed list of sales orders for a customer with extended order information including pricing and line item details.
      tags:
      - Orders
      parameters:
      - name: customerNumber
        in: path
        required: true
        description: Customer account number
        schema:
          type: string
      - name: page
        in: query
        required: false
        schema:
          type: integer
      - name: pageSize
        in: query
        required: false
        schema:
          type: integer
      - name: salesOrderNumber
        in: query
        required: false
        schema:
          type: string
      - name: poNumber
        in: query
        required: false
        schema:
          type: string
      - name: fromDate
        in: query
        required: false
        schema:
          type: string
          format: date
      - name: toDate
        in: query
        required: false
        schema:
          type: string
          format: date
      responses:
        '200':
          description: Detailed order list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderListResponse'
        '401':
          description: Unauthorized
      security:
      - ApiKeyAuth: []
  /salesorder/detail/{customerNumber}/{salesOrderNumber}:
    get:
      operationId: getSalesOrderDetail
      summary: Get Sales Order Detail
      description: Retrieve comprehensive details for a specific sales order including all line items, pricing, ASN information, and status.
      tags:
      - Orders
      parameters:
      - name: customerNumber
        in: path
        required: true
        description: Customer account number
        schema:
          type: string
      - name: salesOrderNumber
        in: path
        required: true
        description: ScanSource sales order number
        schema:
          type: string
      responses:
        '200':
          description: Detailed order information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderDetail'
        '401':
          description: Unauthorized
        '404':
          description: Order not found
      security:
      - ApiKeyAuth: []
  /salesorder/shipquote:
    post:
      operationId: getShippingQuote
      summary: Get Shipping Quote
      description: Generate a shipping quote for an order before submission, including carrier options and estimated costs.
      tags:
      - Shipping
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ShipQuoteRequest'
      responses:
        '200':
          description: Shipping quote options
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShipQuoteResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
      security:
      - ApiKeyAuth: []
  /salesorder/cancel:
    delete:
      operationId: cancelSalesOrder
      summary: Cancel Sales Order
      description: Cancel a pending sales order. Orders that have already shipped cannot be cancelled.
      tags:
      - Orders
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - salesOrderNumber
              properties:
                salesOrderNumber:
                  type: string
                  description: ScanSource order number to cancel
                customerNumber:
                  type: string
                  description: Customer account number
                reason:
                  type: string
                  description: Cancellation reason
      responses:
        '200':
          description: Order successfully cancelled
        '400':
          description: Cannot cancel - order already shipped or invalid
        '401':
          description: Unauthorized
        '404':
          description: Order not found
      security:
      - ApiKeyAuth: []
  /salesorder/tracking:
    get:
      operationId: getOrderTracking
      summary: Get Order Tracking
      description: Retrieve carrier tracking information and delivery status for an order.
      tags:
      - Tracking
      parameters:
      - name: orderNumber
        in: query
        required: false
        description: ScanSource order number
        schema:
          type: string
      - name: poNumber
        in: query
        required: false
        description: Customer purchase order number
        schema:
          type: string
      - name: deliveryNumber
        in: query
        required: false
        description: Delivery or ASN number
        schema:
          type: string
      responses:
        '200':
          description: Tracking information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrackingResponse'
        '401':
          description: Unauthorized
        '404':
          description: Order not found
      security:
      - ApiKeyAuth: []
  /salesorder/serials:
    get:
      operationId: getSerialNumbers
      summary: Get Serial Numbers
      description: Retrieve serial number tracking information for serialized products in an order.
      tags:
      - Tracking
      parameters:
      - name: orderNumber
        in: query
        required: false
        schema:
          type: string
      - name: customerNumber
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Serial number data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SerialNumberResponse'
        '401':
          description: Unauthorized
      security:
      - ApiKeyAuth: []
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Ocp-Apim-Subscription-Key
      description: Azure API Management subscription key from ScanSource partner portal
  schemas:
    SalesOrderRequest:
      type: object
      required:
      - poNumber
      - lineItems
      properties:
        poNumber:
          type: string
          description: Customer purchase order number
        shipToAddress:
          type: object
          properties:
            name:
              type: string
            address1:
              type: string
            address2:
              type: string
            city:
              type: string
            state:
              type: string
            postalCode:
              type: string
            country:
              type: string
        shippingMethod:
          type: string
          description: Preferred shipping carrier/method code
        lineItems:
          type: array
          items:
            type: object
            required:
            - itemNumber
            - quantity
            properties:
              itemNumber:
                type: string
              partNumberType:
                type: string
              quantity:
                type: integer
              unitPrice:
                type: number
              customerItemNumber:
                type: string
    SalesOrderResponse:
      type: object
      properties:
        salesOrderNumber:
          type: string
          description: ScanSource assigned sales order number
        poNumber:
          type: string
          description: Customer purchase order number
        status:
          type: string
          description: Order status
        orderDate:
          type: string
          format: date-time
        lineItems:
          type: array
          items:
            type: object
            properties:
              lineNumber:
                type: integer
              itemNumber:
                type: string
              quantity:
                type: integer
              unitPrice:
                type: number
              status:
                type: string
    AsyncOrderResponse:
      type: object
      properties:
        referenceId:
          type: string
          description: Reference ID for tracking the async order
        status:
          type: string
          description: Initial processing status
        message:
          type: string
    OrderSummaryResponse:
      type: object
      properties:
        totalCount:
          type: integer
        page:
          type: integer
        pageSize:
          type: integer
        orders:
          type: array
          items:
            type: object
            properties:
              salesOrderNumber:
                type: string
              poNumber:
                type: string
              orderDate:
                type: string
                format: date-time
              status:
                type: string
              totalAmount:
                type: number
    OrderListResponse:
      type: object
      properties:
        totalCount:
          type: integer
        orders:
          type: array
          items:
            $ref: '#/components/schemas/OrderDetail'
    OrderDetail:
      type: object
      properties:
        salesOrderNumber:
          type: string
        poNumber:
          type: string
        customerNumber:
          type: string
        orderDate:
          type: string
          format: date-time
        status:
          type: string
        shipToAddress:
          type: object
        lineItems:
          type: array
          items:
            type: object
            properties:
              lineNumber:
                type: integer
              itemNumber:
                type: string
              manufacturerPartNumber:
                type: string
              description:
                type: string
              quantity:
                type: integer
              unitPrice:
                type: number
              extendedPrice:
                type: number
              status:
                type: string
        totalAmount:
          type: number
        currency:
          type: string
    ShipQuoteRequest:
      type: object
      properties:
        customerNumber:
          type: string
        shipToAddress:
          type: object
          properties:
            postalCode:
              type: string
            country:
              type: string
        items:
          type: array
          items:
            type: object
            properties:
              itemNumber:
                type: string
              quantity:
                type: integer
    ShipQuoteResponse:
      type: object
      properties:
        quotes:
          type: array
          items:
            type: object
            properties:
              carrier:
                type: string
              service:
                type: string
              estimatedDays:
                type: integer
              cost:
                type: number
              currency:
                type: string
    TrackingResponse:
      type: object
      properties:
        orderNumber:
          type: string
        packages:
          type: array
          items:
            type: object
            properties:
              trackingNumber:
                type: string
              carrier:
                type: string
              status:
                type: string
              estimatedDelivery:
                type: string
                format: date
              events:
                type: array
                items:
                  type: object
                  properties:
                    date:
                      type: string
                      format: date-time
                    location:
                      type: string
                    description:
                      type: string
    SerialNumberResponse:
      type: object
      properties:
        orderNumber:
          type: string
        serials:
          type: array
          items:
            type: object
            properties:
              itemNumber:
                type: string
              serialNumber:
                type: string
              lineNumber:
                type: integer