openapi: 3.0.3
info:
  title: ArcBest Pickups Shipments API
  description: The ArcBest API provides programmatic access to freight services including LTL rate quotes, shipment booking, tracking, BOL generation, and supply chain visibility. Access to the API is by invitation only.
  version: '2.0'
  x-generated-from: documentation
  contact:
    name: ArcBest
    url: https://www.arcbest.com/
servers:
- url: https://api.arcbest.com/v2
  description: ArcBest API Production
security:
- bearerAuth: []
tags:
- name: Shipments
  description: Shipment booking and management
paths:
  /shipments:
    post:
      operationId: createShipment
      summary: ArcBest Create Shipment
      description: Book a new LTL freight shipment and generate a Bill of Lading.
      tags:
      - Shipments
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ShipmentRequest'
            examples:
              CreateShipmentRequestExample:
                summary: Default createShipment request
                x-microcks-default: true
                value:
                  quoteNumber: Q-20260419-001
                  shipper:
                    name: ACME Corp
                    address: 123 Main St
                    city: Benton
                    state: AR
                    zip: '72015'
                  consignee:
                    name: Widget Inc
                    address: 456 Oak Ave
                    city: Beverly Hills
                    state: CA
                    zip: '90210'
      responses:
        '200':
          description: Shipment created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Shipment'
              examples:
                CreateShipment200Example:
                  summary: Default createShipment 200 response
                  x-microcks-default: true
                  value:
                    proNumber: PRO-123456789
                    bolNumber: BOL-20260419-001
                    status: BOOKED
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - bearerAuth: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    get:
      operationId: listShipments
      summary: ArcBest List Shipments
      description: List shipments with optional filtering by date range and status.
      tags:
      - Shipments
      parameters:
      - name: startDate
        in: query
        description: Start date filter (YYYY-MM-DD)
        schema:
          type: string
          format: date
        example: '2026-04-01'
      - name: endDate
        in: query
        description: End date filter (YYYY-MM-DD)
        schema:
          type: string
          format: date
        example: '2026-04-19'
      - name: status
        in: query
        description: Filter by shipment status
        schema:
          type: string
          enum:
          - BOOKED
          - IN_TRANSIT
          - DELIVERED
          - EXCEPTION
        example: IN_TRANSIT
      responses:
        '200':
          description: List of shipments
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShipmentList'
              examples:
                ListShipments200Example:
                  summary: Default listShipments 200 response
                  x-microcks-default: true
                  value:
                    shipments:
                    - proNumber: PRO-123456789
                      status: IN_TRANSIT
                      origin: Benton, AR
                      destination: Beverly Hills, CA
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - bearerAuth: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    Address:
      type: object
      properties:
        name:
          type: string
          description: Company or person name
          example: ACME Corp
        address:
          type: string
          description: Street address
          example: 123 Main St
        city:
          type: string
          description: City
          example: Benton
        state:
          type: string
          description: State abbreviation
          example: AR
        zip:
          type: string
          description: ZIP code
          example: '72015'
        country:
          type: string
          description: Country code (ISO 3166-1 alpha-2)
          example: US
    ShipmentRequest:
      type: object
      required:
      - shipper
      - consignee
      properties:
        quoteNumber:
          type: string
          description: Rate quote number to use for booking
          example: Q-20260419-001
        shipper:
          $ref: '#/components/schemas/Address'
        consignee:
          $ref: '#/components/schemas/Address'
        items:
          type: array
          items:
            $ref: '#/components/schemas/FreightItem'
        referenceNumber:
          type: string
          description: Customer reference number
          example: PO-98765
    Shipment:
      type: object
      properties:
        proNumber:
          type: string
          description: ArcBest PRO (shipment) number
          example: PRO-123456789
        bolNumber:
          type: string
          description: Bill of Lading number
          example: BOL-20260419-001
        status:
          type: string
          description: Shipment status
          enum:
          - BOOKED
          - PICKED_UP
          - IN_TRANSIT
          - OUT_FOR_DELIVERY
          - DELIVERED
          - EXCEPTION
          example: BOOKED
        quoteNumber:
          type: string
          description: Rate quote number used for booking
          example: Q-20260419-001
    ErrorResponse:
      type: object
      properties:
        message:
          type: string
          description: Error message
          example: Unauthorized access
        code:
          type: integer
          description: Error code
          example: 401
    FreightItem:
      type: object
      properties:
        weight:
          type: number
          description: Weight in pounds
          example: 500
        freightClass:
          type: string
          description: NMFC freight classification
          example: '70'
        pieces:
          type: integer
          description: Number of pieces
          example: 2
        description:
          type: string
          description: Commodity description
          example: Machine parts
        length:
          type: number
          description: Length in inches
          example: 48.0
        width:
          type: number
          description: Width in inches
          example: 40.0
        height:
          type: number
          description: Height in inches
          example: 36.0
    ShipmentList:
      type: object
      properties:
        shipments:
          type: array
          items:
            $ref: '#/components/schemas/Shipment'
        totalCount:
          type: integer
          description: Total number of shipments
          example: 25
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Bearer token obtained from ArcBest API authentication