openapi: 3.0.3
info:
  title: ScanSource Invoice API
  description: The ScanSource Invoice API provides programmatic access to invoicing data for technology distribution partners. Includes invoice summaries, detailed invoice lists, individual invoice details, and PDF export capabilities with filtering by date range and order identifiers.
  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: Invoices
  description: Invoice retrieval and management operations
paths:
  /invoice/summary/{customerNumber}:
    get:
      operationId: getInvoiceSummary
      summary: Get Invoice Summary
      description: Retrieve a paginated summary view of invoices for a customer account, with filtering options by date range, order numbers, and invoice numbers.
      tags:
      - Invoices
      parameters:
      - name: customerNumber
        in: path
        required: true
        description: Customer account number
        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
      - 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 specific 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 date)
        schema:
          type: string
          format: date
      - name: toDate
        in: query
        required: false
        description: End date filter (ISO 8601 date)
        schema:
          type: string
          format: date
      responses:
        '200':
          description: Invoice summary results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvoiceSummaryResponse'
        '401':
          description: Unauthorized - invalid subscription key
        '403':
          description: Forbidden - invalid customer number
      security:
      - ApiKeyAuth: []
  /invoice/list/{customerNumber}:
    get:
      operationId: listInvoices
      summary: List Invoices
      description: Retrieve a detailed list of invoices for a customer with extended invoice information including line items and amounts.
      tags:
      - Invoices
      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: invoiceNumber
        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 invoice list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvoiceListResponse'
        '401':
          description: Unauthorized
      security:
      - ApiKeyAuth: []
  /invoice/detail/{customerNumber}/{invoiceNumber}:
    get:
      operationId: getInvoiceDetail
      summary: Get Invoice Detail
      description: Retrieve comprehensive details for a specific invoice including all line items, pricing, tax information, and shipping details.
      tags:
      - Invoices
      parameters:
      - name: customerNumber
        in: path
        required: true
        description: Customer account number
        schema:
          type: string
      - name: invoiceNumber
        in: path
        required: true
        description: Invoice number to retrieve
        schema:
          type: string
      - name: excludeSerialTracking
        in: query
        required: false
        description: Exclude serial number tracking data from response
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: Detailed invoice information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvoiceDetail'
        '401':
          description: Unauthorized
        '404':
          description: Invoice not found
      security:
      - ApiKeyAuth: []
  /invoice/pdf/{customerNumber}/{invoiceNumber}:
    get:
      operationId: getInvoicePdf
      summary: Get Invoice PDF
      description: Download a PDF copy of a specific invoice for record keeping or sharing with customers.
      tags:
      - Invoices
      parameters:
      - name: customerNumber
        in: path
        required: true
        description: Customer account number
        schema:
          type: string
      - name: invoiceNumber
        in: path
        required: true
        description: Invoice number
        schema:
          type: string
      responses:
        '200':
          description: Invoice PDF file
          content:
            application/pdf:
              schema:
                type: string
                format: binary
        '401':
          description: Unauthorized
        '404':
          description: Invoice not found
      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:
    InvoiceSummaryResponse:
      type: object
      properties:
        totalCount:
          type: integer
          description: Total number of matching invoices
        page:
          type: integer
        pageSize:
          type: integer
        invoices:
          type: array
          items:
            type: object
            properties:
              invoiceNumber:
                type: string
              salesOrderNumber:
                type: string
              poNumber:
                type: string
              invoiceDate:
                type: string
                format: date
              totalAmount:
                type: number
              currency:
                type: string
              status:
                type: string
    InvoiceListResponse:
      type: object
      properties:
        totalCount:
          type: integer
        invoices:
          type: array
          items:
            $ref: '#/components/schemas/InvoiceDetail'
    InvoiceDetail:
      type: object
      properties:
        invoiceNumber:
          type: string
          description: Invoice number
        salesOrderNumber:
          type: string
          description: Associated ScanSource sales order number
        poNumber:
          type: string
          description: Customer purchase order number
        customerNumber:
          type: string
        invoiceDate:
          type: string
          format: date
        dueDate:
          type: string
          format: date
        billToAddress:
          type: object
          properties:
            name:
              type: string
            address1:
              type: string
            city:
              type: string
            state:
              type: string
            postalCode:
              type: string
            country:
              type: string
        shipToAddress:
          type: object
          properties:
            name:
              type: string
            address1:
              type: string
            city:
              type: string
            state:
              type: string
            postalCode:
              type: string
            country:
              type: string
        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
              serialNumbers:
                type: array
                items:
                  type: string
        subtotal:
          type: number
        tax:
          type: number
        shippingCost:
          type: number
        totalAmount:
          type: number
        currency:
          type: string
          default: USD