openapi: 3.0.3
info:
  title: ShipperGuide Shipments API
  version: v3
  description: Optimize shipping operations with ShipperGuide TMS
paths:
  /shipments/:
    post:
      operationId: shipments_create
      description: |-
        This endpoint creates a shipment.

        Use existing data to expedite shipment generation by integrating load-level information.
      summary: Create a shipment
      tags:
      - Shipments API
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ShipmentCreateRequest'
            examples:
              DryVan-FTL:
                value:
                  shipper_uuid: 5c5d1123-948c-4327-bfcc-08536f5f1064
                  equipment_type: DRV
                  mode: FTL
                  shipment_reference: REF987654321
                  auto_create_quotes: false
                  accessorials: []
                  stops:
                  - address: 123 Main St
                    city: Springfield
                    zipcode: '12345'
                    state: IL
                    country: USA
                    index: 0
                    type: pickup
                    planned_date: '2024-01-01'
                    contact:
                      name: John Doe
                      email: john.doe@email.com
                      phone: 5551234567
                      extension: 123
                  - address: 456 Elm St
                    city: Shelbyville
                    zipcode: '67890'
                    state: IL
                    country: USA
                    index: 1
                    type: delivery
                    contact:
                      name: Jane Doe
                      email: jane.doe@email.com
                      phone: 5553214501
                      extension: 123
                summary: Dry Van - FTL
              DryVan-LTL:
                value:
                  shipper_uuid: 5c5d1123-948c-4327-bfcc-08536f5f1064
                  bol_number: BOL123456789
                  equipment_type: DRV
                  mode: LTL
                  shipment_reference: REF987654321
                  mileage: 1200
                  target_rate: '5000'
                  auto_create_quotes: true
                  accessorials: ['lift-gate-pickup', 'residential-pickup']
                  stops:
                  - facility_name: ABC Warehouse
                    address: 123 Main St
                    zipcode: '12345'
                    city: Springfield
                    state: IL
                    country: USA
                    index: 0
                    type: pickup
                    planned_date: '2024-01-01'
                    instructions: Load pallets from dock 3
                    contact:
                      name: John Doe
                      email: john.doe@email.com
                      phone: 5551234567
                      extension: 123
                  - facility_name: XYZ Distribution Center
                    address: 456 Elm St
                    zipcode: '67890'
                    city: Shelbyville
                    state: IL
                    country: USA
                    index: 1
                    type: delivery
                    planned_date: '2024-01-02'
                    instructions: Unload at bay 2
                    contact:
                      name: Jane Doe
                      email: jane.doe@email.com
                      phone: 5553214501
                      extension: 123
                  handling_units:
                  - quantity: 10
                    type: std_pallets
                    height: '48'
                    length: '48'
                    width: '40'
                    stackable: true
                    turnable: true
                    po_numbers:
                    - PO12345
                    so_numbers:
                    - SO67890
                    pickup_stop_index: 0
                    delivery_stop_index: 1
                    movement: outbound
                    commodities:
                    - description: Food Goods
                      quantity: 10
                      weight: '17225.20'
                      freight_class: '70'
                      nmfc_code: '123456'
                summary: Dry Van - LTL
        required: true
      security:
      - jwt: []
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShipmentCreateResponse'
          description: ''
  /shipments/resolve-uuids:
    get:
      operationId: shipments_resolve_uuids_retrieve
      summary: Find shipment UUIDs by alternative references
      description: Find shipment UUIDs using alternative reference numbers such as carrier reference number or ShipperGuide ID. You can provide one or more query parameters in a single request to narrow down results.
      parameters:
      - in: query
        name: carrier_ref_number
        schema:
          type: string
        description: Carrier's reference number for the shipment
      - in: query
        name: shipperguide_id
        schema:
          type: string
        description: ShipperGuide ID for the shipment
      tags:
      - Shipments API
      security:
      - jwt: []
      responses:
        '200':
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                  format: uuid
          description: 'Array of shipment UUIDs matching the provided reference numbers'
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: 'Bad request, missing or invalid parameters'
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: 'Permission denied'            
  /shipments/{shipment_id}/charges:
    post:
      operationId: shipments_charge_create
      description: Creates a charge for the specified shipment and returns the id of the charge created.
      summary: Create a shipment charge
      parameters:
        - in: path
          name: shipment_id
          schema: 
            type: string
            format: uuid
          description: UUID of the shipment
          required: true
      tags:
        - Shipments API
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ShipmentChargeCreateRequest'
            examples:
              Single charge:
                value: 
                  charge_type_code: detention
                  quantity: 1
                  rate: 80.50
                  notes: "Lorem ipsum dolor sit amet..."
              Multiple charges:
                value:
                  charge_type_code: detention
                  quantity: 2
                  rate: 45.25
                  notes: "Lorem ipsum dolor sit amet..."
        required: true
      security:
        - jwt: [ ]
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShipmentChargeCreateResponse'
              examples:
                Charge created:
                  value:
                    uuid: f3b40e85-8ce1-41eb-ab20-d32d0952adeb
                  summary: Successful charge creation
          description: ''
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: ''
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: ''
  /shipments/{shipment_id}/stop-events:
    post:
      operationId: shipments_stop_events_create
      description: Submit an update about a shipment’s execution, indicating whether
        the truck has arrived at or departed from a stop.
      summary: Submit a shipment milestone
      parameters:
        - in: path
          name: shipment_id
          schema:
            type: string
            format: uuid
          description: UUID of the shipment.
          required: true
      tags:
        - Shipments API
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ShipmentMilestoneSubmit'
            examples:
              Check-in:
                value:
                  type: check-in
                  occurred_at: '2025-03-27T19:23:35.283Z'
                  stop:
                    index: 1
                summary: Check-in
        required: true
      security:
        - jwt: [ ]
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShipmentMilestoneSubmit'
              examples:
                Check-in:
                  value:
                    type: check-in
                    occurred_at: '2025-03-27T19:23:35.283Z'
                    stop:
                      index: 1
                  summary: Check-in
          description: ''
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: ''
  /shipments/{shipment_id}/invoices/{invoice_id}:
    get:
      operationId: shipments_invoices_retrieve
      summary: Retrieve a shipment invoice
      description: Retrieve a shipment invoice by its UUID.
      parameters:
        - in: path
          name: shipment_id
          schema:
            type: string
            format: uuid
          description: UUID of the shipment.
          required: true
        - in: path
          name: invoice_id
          schema:
            type: string
            format: uuid
          description: UUID of the invoice.
          required: true
      tags:
        - Shipments API
      security:
        - jwt: [ ]
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  uuid:
                    type: string
                    format: uuid
                    description: Unique identifier for the invoice
                  number:
                    type: string
                    description: Invoice number or reference label
                  url:
                    type: string
                    format: uri
                    description: Direct URL to access the invoice document
                  uploaded_at:
                    type: string
                    format: date-time
        '403':
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/GenericError'
            description: 'Permission denied'
        '404':
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/GenericError'
            description: 'Invoice or shipment not found'
  /shipments/{shipment_id}/charges/{charge_id}/cancel:
    post:
      operationId: shipments_charge_cancel
      description: Cancels a charge for the specified shipment.
      summary: Cancels a shipment charge
      parameters:
        - in: path
          name: shipment_id
          schema:
            type: string
            format: uuid
          description: UUID of the shipment
          required: true        
        - in: path
          name: charge_id
          schema:
            type: string
            format: uuid
          description: UUID of the charge
          required: true
      tags:
        - Shipments API
      security:
        - jwt: [ ]
      responses:
        '204':
          description: ''
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: ''
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: ''
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: ''
  /shipments/{shipment_uuid}/cancel:
    post:
      operationId: shipments_cancel_create
      description: Cancel the shipment.
      summary: Cancel an active shipment
      parameters:
      - in: path
        name: shipment_id
        schema:
          type: string
          format: uuid
        description: UUID of the shipment.
        required: true
      tags:
      - Shipments API
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ShipmentCancel'
      security:
      - jwt: []
      responses:
        '204':
          description: No response body
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: ''
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
              examples:
                UnprocessableEntity:
                  value:
                    code: unprocessable_entity
                    message: Cannot cancel shipment.
                    extra:
                      shipment_status: tendering
                  summary: Cannot cancel shipment
          description: ''
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
              examples:
                Forbidden:
                  value:
                    code: forbidden
                    message: You do not have permission to perform this action.
                    extra: {}
          description: ''
  /shipments/{shipment_uuid}/appointments/{appt_uuid}/confirm:
    post:
      operationId: shipments_appointments_confirm_create
      description: Confirm an appointment
      summary: Confirm an appointment
      parameters:
        - in: path
          name: appt_uuid
          schema:
            type: string
            format: uuid
          description: UUID of the Appointment.
          required: true
        - in: path
          name: shipment_uuid
          schema:
            type: string
            format: uuid
          description: UUID of the Shipment.
          required: true
      tags:
        - Shipments API
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AppointmentConfirmRequest'
      security:
        - jwt: [ ]
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppointmentConfirmResponse'
          description: ''
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: ''
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: ''
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: ''
  /shipments/{shipment_uuid}/appointments:
    get:
      operationId: shipments_appointments_list
      description: Retrieves a list of all appointments belonging to a specific shipment.
      summary: List Appointments for a Shipment
      parameters:
        - in: path
          name: shipment_uuid
          schema:
            type: string
            format: uuid
          description: UUID of the Shipment.
          required: true
      tags:
        - Shipments API
      security:
        - jwt: [ ]
      responses:
        '200':
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Appointment'
          description: ''
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: ''
components:
  schemas:
    Appointment:
      type: object
      properties:
        confirmation_number:
          type: string
          nullable: true
          maxLength: 255
        created_at:
          type: string
          format: date-time
          readOnly: true
        loading_type:
          $ref: '#/components/schemas/LoadingTypeEnum'
        misscheduling_note:
          type: string
          nullable: true
        misscheduling_reason:
          nullable: true
          oneOf:
            - $ref: '#/components/schemas/MisschedulingReasonEnum'
            - $ref: '#/components/schemas/BlankEnum'
            - $ref: '#/components/schemas/NullEnum'
        mode:
          $ref: '#/components/schemas/ModeBcfEnum'
        scheduled_at:
          type: string
          format: date-time
          nullable: true
        scheduled_window_end:
          type: string
          format: date-time
          nullable: true
        scheduled_window_start:
          type: string
          format: date-time
          nullable: true
        status:
          allOf:
            - $ref: '#/components/schemas/StatusEnum'
          readOnly: true
        stop_date:
          type: string
          format: date
          nullable: true
          readOnly: true
        stop_index:
          type: integer
          readOnly: true
        stop_timezone:
          type: string
          readOnly: true
        suggested_window_end:
          type: string
          format: date-time
          nullable: true
        suggested_window_start:
          type: string
          format: date-time
          nullable: true
        updated_at:
          type: string
          format: date-time
          readOnly: true
        uuid:
          type: string
          format: uuid
          readOnly: true
      required:
        - created_at
        - status
        - stop_date
        - stop_index
        - stop_timezone
        - updated_at
        - uuid
    AppointmentConfirmRequest:
      type: object
      properties:
        confirmation_number:
          type: string
          nullable: true
          maxLength: 255
        loading_type:
          $ref: '#/components/schemas/LoadingTypeEnum'
        misscheduling_note:
          type: string
          nullable: true
        misscheduling_reason:
          nullable: true
          oneOf:
            - $ref: '#/components/schemas/MisschedulingReasonEnum'
            - $ref: '#/components/schemas/BlankEnum'
            - $ref: '#/components/schemas/NullEnum'
        mode:
          $ref: '#/components/schemas/ModeBcfEnum'
        scheduled_window_end:
          type: string
          format: date-time
          nullable: true
        scheduled_window_start:
          type: string
          format: date-time
          nullable: true
    NullEnum:
      enum:
      - null
    StatusEnum:
      enum:
        - pending
        - requested
        - confirmed
      type: string
      description: |-
        * `pending` - Pending
        * `requested` - Requested
        * `confirmed` - Confirmed
    AppointmentConfirmResponse:
      type: object
      properties:
        scheduled_at:
          type: string
          format: date-time
          nullable: true
    BlankEnum:
      enum:
        - ''
    LoadingTypeEnum:
      enum:
      - live
      - drop
      type: string
      description: |-
        * `live` - Live
        * `drop` - Drop
    MisschedulingReasonEnum:
      enum:
      - first-available
      - insufficient-lead-time
      - traffic-or-weather-delays
      - other
      type: string
      description: |-
        * `first-available` - First Available Appointment
        * `insufficient-lead-time` - Insufficient Lead Time
        * `traffic-or-weather-delays` - Traffic or Weather Delays
        * `other` - Other
    ModeBcfEnum:
      enum:
      - appt
      - fcfs
      type: string
      description: |-
        * `appt` - Appointment
        * `fcfs` - First come, first served
    CountryEnum:
      enum:
      - USA
      - CAN
      type: string
      description: |-
        * `USA` - United States
        * `CAN` - Canada
    EquipmentTypeEnum:
      enum:
      - DRV
      - RFR
      type: string
      description: |-
        * `DRV` - Dry Van
        * `RFR` - Reefer
    FreightClassEnum:
      enum:
      - '50'
      - '55'
      - '60'
      - '65'
      - '70'
      - '77.5'
      - '85'
      - '92.5'
      - '100'
      - '110'
      - '125'
      - '150'
      - '175'
      - '200'
      - '250'
      - '300'
      - '400'
      - '500'
      type: string
      description: |-
        * `50` - 50
        * `55` - 55
        * `60` - 60
        * `65` - 65
        * `70` - 70
        * `77.5` - 77.5
        * `85` - 85
        * `92.5` - 92.5
        * `100` - 100
        * `110` - 110
        * `125` - 125
        * `150` - 150
        * `175` - 175
        * `200` - 200
        * `250` - 250
        * `300` - 300
        * `400` - 400
        * `500` - 500
    GenericError:
      type: object
      description: Standard format for all API error responses.
      properties:
        code:
          type: string
          description: The code of the error returned.
        message:
          type: string
          description: Human readable error description.
        extra:
          type: object
          additionalProperties: { }
          description: Extra data about the error.
      required:
        - code
        - extra
        - message
    ModeEnum:
      enum:
      - FTL
      - PTL
      - LTL
      - IMDL
      type: string
      description: |-
        * `FTL` - Full Truckload
        * `PTL` - Partial Truckload
        * `LTL` - Less-Than-Truckload
        * `IMDL` - Intermodal
    MovementEnum:
      enum:
      - inbound
      - outbound
      - transfer
      type: string
      description: |-
        * `inbound` - Inbound
        * `outbound` - Outbound
        * `transfer` - Transfer
    PackageTypeEnum:
      enum:
      - bags
      - boxes
      - bulk_containers
      - bundles_and_rolls
      - cartons
      - drums
      - gas_cylinders
      - jerricans
      - pails_or_cans
      - pieces
      - totes_or_tanks
      type: string
      description: |-
        * `bags` - Bags
        * `boxes` - Boxes
        * `bulk_containers` - Bulk Containers
        * `bundles_and_rolls` - Bundles and Rolls
        * `cartons` - Cartons
        * `drums` - Drums
        * `gas_cylinders` - Gas Cylinders
        * `jerricans` - Jerricans
        * `pails_or_cans` - Pails or Cans
        * `pieces` - Pieces
        * `totes_or_tanks` - Totes or Tanks
    AccessorialsEnum:
      enum:
      - protect_from_freeze
      - lift-gate-pickup
      - residential-pickup
      - inside-pickup
      - tradeshow_pickup
      - limited-access-pickup
      - construction-site-pickup
      - appointment-pickup
      - notify-prior-to-arrival-delivery
      - lift-gate-delivery
      - residential-delivery
      - inside-delivery
      - limited-access-delivery
      - grocery-warehouse-delivery
      - tradeshow_delivery
      - construction-site-delivery
      - appointment-delivery
      - team_service
      - driver_assist_pickup
      - driver_assist_delivery
      - pallet_jack_pickup
      - pallet_jack_delivery
      - stop_off_pickup
      - stop_off_delivery
      - high_value
      - forklift_pickup
      - forklift_delivery
      - sort-segregate-pickup
      - sort-segregate-delivery
      type: string
      description: |-
        * `protect_from_freeze` - Protect goods from freezing
        * `lift-gate-pickup`- Pickup facility has a lift gate
        * `residential-pickup`- Pickup will happen at a residential address
        * `inside-pickup`-  Pickup will happen inside a building or facility
        * `tradeshow_pickup`- Pickup of goods at a tradeshow or exhibition
        * `limited-access-pickup`- Pickup at a location with limited access
        * `construction-site-pickup`- Pickup at a construction site
        * `appointment-pickup`- Pickup requires an appointment
        * `notify-prior-to-arrival-delivery`- Notify the facility before arrival for delivery
        * `lift-gate-delivery`- Delivery facility has a lift gate
        * `residential-delivery`- Delivery will happen at a residential address
        * `inside-delivery`- Delivery will happen inside a building or facility
        * `limited-access-delivery`- Delivery at a location with limited access
        * `grocery-warehouse-delivery`- Delivery to a grocery warehouse
        * `tradeshow_delivery`- Delivery of goods at a tradeshow or exhibition
        * `construction-site-delivery`- Delivery at a construction site
        * `appointment-delivery`- Delivery requires an appointment
        * `team_service`- Team service for loading or unloading
        * `driver_assist_pickup`- Pickup requires driver assistance
        * `driver_assist_delivery`- Delivery requires driver assistance
        * `pallet_jack_pickup`- Pickup loading will be done using a pallet jack
        * `pallet_jack_delivery`- Delivery unloading will be done using a pallet jack
        * `stop_off_pickup`- Pickup will include a stop-off
        * `stop_off_delivery`- Delivery will include a stop-off
        * `high_value`- High value goods that require special handling or security
        * `forklift_pickup`- Pickup loading will be done using a forklift
        * `forklift_delivery`- Delivery loading will be done using a forklift
        * `sort-segregate-pickup`- Pickup requires sort and segregation of goods
        * `sort-segregate-delivery`- Delivery requires sort and segregation of goods
    StopContact:
      type: object
      properties:
        name:
          type: string
          description: "Contact's name."
          example: "John Doe"
        email:
          type: string
          format: email
          description: "Contact's e-mail address."
          example: "john.doe@email.com"
        phone:
          type: string
          format: phone
          description: "Contact's phone number."
          example: "+15551234567"
        extension:
          type: string
          description: "Contact's phone number extension."
          example: "123"
    ShipmentCreateRequest:
      type: object
      properties:
        shipper_uuid:
          type: string
          format: uuid
          description: Unique identifier of the shipper that owns this shipment.
        bol_number:
          type: string
          description: BOL Number.
          maxLength: 100
        equipment_type:
          allOf:
          - $ref: '#/components/schemas/EquipmentTypeEnum'
          description: Equipment. The API currently accepts either Dry Van or Reefer.
        mode:
          allOf:
          - $ref: '#/components/schemas/ModeEnum'
          description: |
            Mode of transportation, and the valid modes depend on the Equipment:
            - Dry Van works with FTL, PLT, LTL, IMDL
            - Reefer works for FTL, IMDL
        shipment_reference:
          type: string
          description: Internal customer reference such as the load identifier.
          maxLength: 255
        mileage:
          type: integer
          minimum: 0
          description: |
            Mileage. The total distance between first and last stop.
            If the customer doesn't provide it, the system will calculate it.
        target_rate:
          type: string
          format: decimal
          pattern: ^-?\d{0,10}(?:\.\d{0,3})?$
          description: |
            A target rate is the price the customer would like to pay for the shipment.
            This data is essential if the customer uses the Book it Now functionality.
        auto_create_quotes:
          type: boolean
          description: |
            If true, the system will automatically create quotes for the shipment.
            If false or blank, the system will not create quotes.
            If the shipment stops are in the past, the quote will also not be created.
        accessorials:
          type: array
          items:
            type: string
            allOf:
            - $ref: '#/components/schemas/AccessorialsEnum'
            maxLength: 255
          description: List of accessorial services needed for the haul.
        stops:
          type: array
          items:
            $ref: '#/components/schemas/ShipmentCreateRequestStop'
          description: Stops indicate the shipment's pickup and drop-off locations.
        handling_units:
          type: array
          items:
            $ref: '#/components/schemas/ShipmentCreateRequestHandlingUnit'
          description: |
            This represents the handling units that will be moved within a shipment, at the level that the freight will be loaded and unloaded.
            If the customer is declaring a PTL/LTL shipment, handling units information is mandatory.
      required:
      - equipment_type
      - mode
      - shipper_uuid
      - stops
    ShipmentCreateRequestHandlingUnit:
      type: object
      properties:
        quantity:
          type: integer
          minimum: 0
          title: Package Count
          description: Number of handling units being described.
        type:
          allOf:
          - $ref: '#/components/schemas/ShipmentCreateRequestHandlingUnitTypeEnum'
          title: Handling Unit Type
          description: Handling unit type.
        height:
          type: string
          format: decimal
          pattern: ^-?\d{0,6}(?:\.\d{0,5})?$
          description: Height of the package, in inches.
        length:
          type: string
          format: decimal
          pattern: ^-?\d{0,6}(?:\.\d{0,5})?$
          description: Length of the package, in inches.
        width:
          type: string
          format: decimal
          pattern: ^-?\d{0,6}(?:\.\d{0,5})?$
          description: Width of the package, in inches.
        stackable:
          type: boolean
          description: Indicates if handling units can be stacked.
        turnable:
          type: boolean
          description: Indicates if handling units can be turned.
        po_numbers:
          type: array
          items:
            type: string
            maxLength: 255
          description: Purchase Order Numbers.
        so_numbers:
          type: array
          items:
            type: string
            maxLength: 255
          description: Sales Order Numbers.
        pickup_stop_index:
          type: integer
          minimum: 0
          description: Use to indicate at what pickup stop this handling unit will
            be collected.
        delivery_stop_index:
          type: integer
          minimum: 0
          description: Use to indicate at what delivery stop this handling unit will
            be dropped off.
        max_temperature:
          type: number
          format: double
          title: Max. Temperature
          description: Max temperature, in Fahrenheit. If the customer provides a
            temp for a given handling unit, the entire shipment becomes temperature-controlled.
        movement:
          allOf:
          - $ref: '#/components/schemas/MovementEnum'
          description: Indicates the movement type for this handling unit. Stored
            for reporting purposes only.
        commodities:
          type: array
          items:
            $ref: '#/components/schemas/ShipmentCreateRequestHandlingUnitCommodity'
          description: The commodities or items that will be conveyed with the shipment.
    ShipmentCreateRequestHandlingUnitCommodity:
      type: object
      properties:
        description:
          type: string
          title: Commodity Name
          description: Commodity name.
          maxLength: 255
        package_type:
          allOf:
          - $ref: '#/components/schemas/PackageTypeEnum'
          description: Package type.
        quantity:
          type: integer
          minimum: 0
          description: Quantity.
        weight:
          type: string
          format: decimal
          pattern: ^-?\d{0,6}(?:\.\d{0,5})?$
          description: |
            Weight of the package, in pounds (LB).
            Values must be positive and contain up to two decimal digits.

            Note that the lowest value is 1 and the maximum value is determined by the equipment_type: 45000 for DRV, 43000 for RFR.
            If the weight is not specified, it is set to the maximum allowable for the equipment_type.
        freight_class:
          allOf:
          - $ref: '#/components/schemas/FreightClassEnum'
          title: Class
          description: Freight Class is used in interstate, intrastate, and international
            commerce for LTL (less than truckload) shipments.
        nmfc_code:
          type: string
          title: NMFC
          description: The NMFC Number for the commodity.
          maxLength: 255
    ShipmentCreateRequestHandlingUnitTypeEnum:
      enum:
      - bags
      - bales
      - boxes
      - bunches
      - carpets
      - coils
      - crates
      - cylinders
      - drums
      - loose
      - pails
      - pallets_non_std
      - reels
      - rolls
      - std_pallets
      - tubes_pipes
      - ubox
      type: string
      description: |-
        * `bags` - Bags
        * `bales` - Bales
        * `boxes` - Boxes
        * `bunches` - Bunches
        * `carpets` - Carpets
        * `coils` - Coils
        * `crates` - Crates
        * `cylinders` - Cylinders
        * `drums` - Drums
        * `loose` - Loose
        * `pails` - Pails
        * `pallets_non_std` - Pallets Non Standard
        * `reels` - Reels
        * `rolls` - Rolls
        * `std_pallets` - Standard Pallets/Skids (48x40)
        * `tubes_pipes` - Tubes and Pipes
        * `ubox` - U-Box
    ShipmentCreateRequestStop:
      type: object
      properties:
        facility_name:
          type: string
          description: The Facility's name.
          maxLength: 255
        address:
          type: string
          description: Address of the facility.
          maxLength: 255
        zipcode:
          type: string
          description: |
            Postal code of the address.
            Accepts:
            - 5-digit for USA (eg: 10108)
            - 6-digit for CAN (eg: N3H 4R7)
          maxLength: 7
          minLength: 5
        city:
          type: string
          description: City of the address.
          maxLength: 100
        state:
          type: string
          description: State of the address. Accepts two-letter abbreviations for
            the states in the USA and CAN.
          maxLength: 2
        country:
          allOf:
          - $ref: '#/components/schemas/CountryEnum'
          description: Country code for the address.
        index:
          type: integer
          minimum: 0
          title: Stop Index
          description: Indicates the order of the stops. The first one must be 0.
        type:
          allOf:
          - $ref: '#/components/schemas/ShipmentCreateRequestStopTypeEnum'
          title: Stop Type
          description: |
            Up to 14 stops allowed, with the first being the pick-up, and the last a delivery.
            If not declared, the first stop will be created as a pickup and all subsequent stops will be set as deliveries.
        planned_date:
          type: string
          format: date
          title: Date
          description: The planned date of the stop, in the form YYYY-MM-DD. It is
            required for the first stop.
        instructions:
          type: string
          title: Instructions (or Notes)
          description: Facility instructions (or Notes) that will be saved for future
            shipment creations.
        contact:
          type: object
          description: "Point of contact at the facility."
          $ref: '#/components/schemas/StopContact'
      required:
      - address
      - city
      - country
      - index
      - state
      - zipcode
    ShipmentCreateRequestStopTypeEnum:
      enum:
      - pickup
      - delivery
      type: string
      description: |-
        * `pickup` - Pickup
        * `delivery` - Delivery
    ShipmentCreateResponse:
      type: object
      properties:
        uuid:
          type: string
          format: uuid
          title: Shipment UUID
          description: Unique identifier of the shipment.
      required:
      - uuid
    ShipmentMilestoneStop:
      type: object
      properties:
        index:
          type: integer
          title: Stop index
          description: Index of the stop, starting from 0 (pickup).
      required:
        - index
    ShipmentChargeCreateRequest:
      type: object
      properties: 
        charge_type_code:
          type: string
          title: Charge type code
          description: Type of the charge you wish to create. It can be any string.
        quantity:
          type: integer
          title: Quantity
          description: Amount of charges.
        rate:
          format: decimal
          pattern: ^-?\d{0,11}(?:\.\d{0,2})?$
          title: Rate
          description: Cost of a single charge. Accepts numbers up to 13 digits, included the 2 decimal places precision.
        notes:
          type: string
          title: Notes
          description: Any notes you might add to the charge being created.
          default: ""
      required: 
        - charge_type_code
        - quantity
        - rate
    ShipmentChargeCreateResponse:
      type: object
      properties:
        uuid:
          type: string
          format: uuid
          title: Charge UUID
          description: Unique identifier of the charge created.
      required:
        - uuid
    ShipmentCancel:
      type: object
      properties:
        reason:
          type: string
          nullable: true
          description: Reason for canceling the shipment.
    ShipmentMilestoneSubmit:
      type: object
      properties:
        type:
          allOf:
            - $ref: '#/components/schemas/ShipmentMilestoneSubmitTypeEnum'
          title: Event type
          description: Event type (e.g. check-in).
        occurred_at:
          type: string
          format: date-time
          title: Event occurred at
          description: Timestamp of when the event occurred.
        stop:
          $ref: '#/components/schemas/ShipmentMilestoneStop'
      required:
        - occurred_at
        - stop
        - type
    ShipmentMilestoneSubmitTypeEnum:
      enum:
        - check-in
        - check-out
      type: string
      description: |-
        * `check-in` - Check-in
        * `check-out` - Check-out
  securitySchemes:
    jwt:
      type: http
      scheme: bearer
      bearerFormat: JWT
servers:
- url: https://api.loadsmart.com/api/v3
  description: Production environment
tags:
- name: Shipments API
  description: This object represents the shipments of your business.
