openapi: 3.0.3
info:
  title: ShipperGuide Shipments API
  description: Optimize shipping operations with ShipperGuide TMS
  version: v3
paths:
  /shipments:
    get:
      summary: List shipments
      description: |
        Returns a paginated list of shipments for the authenticated shipper context.
        Supports filtering by status, mode, equipment type, dates, carrier, BOL, SO/PO numbers,
        shipper reference, ShipperGuide ID, and shipper custom fields.
      operationId: listShipments
      tags:
        - Shipments API
      parameters:
        - name: shipper_uuid
          in: query
          required: true
          schema:
            type: string
            format: uuid
          description: UUID of the shipper.
        - name: status
          in: query
          required: false
          schema:
            type: string
          description: Comma-separated shipment statuses to filter by (e.g. `booked,delivered`).
        - name: mode
          in: query
          required: false
          schema:
            type: string
          description: Comma-separated modes to filter by (e.g. `FTL,LTL`).
        - name: equipment_type
          in: query
          required: false
          schema:
            type: string
          description: Comma-separated equipment types to filter by.
        - name: created_at_after
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: Filter shipments created at or after this datetime (ISO 8601).
        - name: created_at_before
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: Filter shipments created at or before this datetime (ISO 8601).
        - name: carrier_name
          in: query
          required: false
          schema:
            type: string
          description: Filter by carrier name (case-insensitive partial match).
        - name: bol_number
          in: query
          required: false
          schema:
            type: string
          description: Filter by exact BOL number.
        - name: so_number
          in: query
          required: false
          schema:
            type: string
          description: Comma-separated SO numbers; shipment matches if it has any of these (matches any).
        - name: po_number
          in: query
          required: false
          schema:
            type: string
          description: Comma-separated PO numbers; shipment matches if it has any of these (matches any).
        - name: shipment_reference
          in: query
          required: false
          schema:
            type: string
          description: Filter by shipper reference number (exact match).
        - name: shipperguide_id
          in: query
          required: false
          schema:
            type: string
          description: Filter by ShipperGuide ID (exact match).
        - name: shipper_custom_fields
          in: query
          required: false
          deprecated: true
          schema:
            type: object
          description: |
            **Deprecated:** Use `custom_fields` instead. This parameter will be removed in a future release.

            Filter by custom fields. Pass encoded JSON key-value pairs; shipment matches if it contains all specified pairs.

            Example: To filter by `{"custom_field": "custom_value"}` Use: `?shipper_custom_fields=%7B%22custom_field%22%3A%20%22custom_value%22%7D`
        - name: custom_fields
          in: query
          required: false
          schema:
            type: object
          description: |
            Filter by custom fields. Pass encoded JSON key-value pairs; shipment matches if it contains all specified pairs.

            Example: To filter by `{"custom_field": "custom_value"}` Use: `?custom_fields=%7B%22custom_field%22%3A%20%22custom_value%22%7D`
        - name: page
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            default: 1
          description: Page number for pagination.
        - name: max_per_page
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 50
            default: 20
          description: Maximum number of items per page.
      security:
        - jwt: []
      responses:
        '200':
          description: Paginated list of shipments.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShipmentListResponse'
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: Bad request. Invalid query parameters provided.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: Forbidden. Authentication credentials are not valid or insufficient
            permissions.
        '401':
          description: Unauthorized – missing or invalid authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedDetail'
    post:
      operationId: root_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: []
                  trailer_number: '1Y5SC89B1A3456789'
                  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'
                  trailer_number: '1Y5SC89B1A3456789'
                  auto_create_quotes: true
                  accessorials:
                  - lift-gate-pickup
                  - residential-delivery
                  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:
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitExceededError'
          description: ''
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShipmentCreateResponse'
          description: ''
  /shipments/{shipment_id}:
    get:
      summary: Get shipment detail
      description: Retrieve full details of a single shipment by UUID
      operationId: getShipmentDetail
      tags:
        - Shipments API
      parameters:
        - name: shipment_id
          in: path
          required: true
          description: Unique identifier of the shipment (UUID)
          schema:
            type: string
            format: uuid
        - name: shipper_uuid
          in: query
          required: true
          description: Shipper unique identifier (UUID)
          schema:
            type: string
            format: uuid
      security:
        - jwt: []
      responses:
        "200":
          description: Shipment detail
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ShipmentDetail"
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: Bad request. Invalid query parameters provided.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: Forbidden. Authentication credentials are not valid or insufficient
            permissions.
        '401':
          description: Unauthorized – missing or invalid authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedDetail'
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: Shipment not found.
  /shipments/{shipment_id}/appointments:
    get:
      operationId: 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_id
        schema:
          type: string
          format: uuid
        description: UUID of the Shipment.
        required: true
      tags:
      - Shipments API
      security:
      - jwt: []
      responses:
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitExceededError'
          description: ''
        '200':
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Appointment'
          description: ''
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: ''
  /shipments/{shipment_id}/appointments/{appt_id}/confirm:
    post:
      operationId: appointments_confirm_create
      description: Confirm an appointment
      summary: Confirm an appointment
      parameters:
      - in: path
        name: appt_id
        schema:
          type: string
          format: uuid
        description: UUID of the Appointment.
        required: true
      - 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/AppointmentConfirmRequest'
      security:
      - jwt: []
      responses:
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitExceededError'
          description: ''
        '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_id}/cancel:
    post:
      operationId: 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:
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitExceededError'
          description: ''
        '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_id}/charges:
    post:
      operationId: charges_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/ShipmentChargeCreate'
            examples:
              SingleCharge:
                value:
                  charge_type_code: detention
                  quantity: 1
                  rate: 80.5
                  notes: Lorem ipsum dolor sit amet...
                summary: Single charge
              MultipleCharges:
                value:
                  charge_type_code: detention
                  quantity: 2
                  rate: 45.25
                  notes: Lorem ipsum dolor sit amet...
                summary: Multiple charges
        required: true
      security:
      - jwt: []
      responses:
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitExceededError'
          description: ''
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShipmentCharge'
              examples:
                ChargeCreated:
                  value:
                    uuid: f3b40e85-8ce1-41eb-ab20-d32d0952adeb
                  summary: Successful charge creation
          description: ''
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: ''
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: ''
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: ''
  /shipments/{shipment_id}/charges/{charge_id}/cancel:
    post:
      operationId: charges_cancel_create
      description: Cancels a charge for the specified shipment.
      summary: Cancels a shipment charge
      parameters:
      - in: path
        name: charge_id
        schema:
          type: string
          format: uuid
        description: UUID of the charge.
        required: true
      - in: path
        name: shipment_id
        schema:
          type: string
          format: uuid
        description: UUID of the shipment.
        required: true
      tags:
      - Shipments API
      security:
      - jwt: []
      responses:
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitExceededError'
          description: ''
        '204':
          description: No response body
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: ''
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: ''
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: ''
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: ''
  /shipments/{shipment_id}/invoices/{invoice_id}:
    get:
      operationId: invoices_retrieve
      description: Retrieve details of a specific invoice within a shipment.
      summary: Get Shipment Invoice
      parameters:
      - in: path
        name: invoice_id
        schema:
          type: string
          format: uuid
        description: UUID of the invoice
        required: true
      - in: path
        name: shipment_id
        schema:
          type: string
          format: uuid
        description: UUID of the shipment
        required: true
      tags:
      - Shipments API
      security:
      - jwt: []
      responses:
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitExceededError'
          description: ''
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShipmentInvoiceResponse'
          description: ''
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: ''
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: ''
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: Invoice or shipment not found.
  /shipments/{shipment_id}/stop-events:
    post:
      operationId: 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:
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitExceededError'
          description: ''
        '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: ''
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: ''
  /shipments/resolve-uuids:
    get:
      operationId: resolve_uuids_retrieve
      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.
      summary: Find shipment UUIDs by alternative references
      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:
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitExceededError'
          description: ''
        '200':
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                  format: uuid
                description: Array of shipment UUIDs matching the provided reference
                  numbers.
          description: ''
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: Bad request. Invalid query parameters provided.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: Forbidden. Authentication credentials are not valid or insufficient
            permissions.
  /shipments/{shipment_id}/rates:
    get:
      summary: List rates for a shipment
      description: |
        Returns all rates associated with the shipment's spot quote.
        If the shipment has no spot quote, returns an empty list.
        Only shippers with a valid shipper context may access this endpoint.
      operationId: listShipmentRates
      tags:
        - Shipments API
      parameters:
        - name: shipment_id
          in: path
          required: true
          description: Unique identifier of the shipment (UUID)
          schema:
            type: string
            format: uuid
        - name: shipper_uuid
          in: query
          required: true
          description: Shipper unique identifier (UUID)
          schema:
            type: string
            format: uuid
        - name: carrier_name
          in: query
          required: false
          description: Filter by carrier name (case-insensitive partial match).
          schema:
            type: string
        - name: carrier_mc
          in: query
          required: false
          description: Filter by carrier MC number (exact match).
          schema:
            type: string
        - name: carrier_dot
          in: query
          required: false
          description: Filter by carrier DOT number (exact match).
          schema:
            type: string
        - name: carrier_scac
          in: query
          required: false
          description: Filter by carrier SCAC (case-insensitive partial match).
          schema:
            type: string
        - name: ltl_carrier_name
          in: query
          required: false
          description: Filter by LTL carrier name (case-insensitive partial match).
          schema:
            type: string
        - name: ltl_carrier_scac
          in: query
          required: false
          description: Filter by LTL carrier SCAC (case-insensitive partial match).
          schema:
            type: string
        - name: status
          in: query
          required: false
          description: Comma-separated rate statuses to filter by (e.g. `available,pending`).
          schema:
            type: string
        - name: service_level
          in: query
          required: false
          description: Comma-separated service levels to filter by.
          schema:
            type: string
      security:
        - jwt: []
      responses:
        "200":
          description: List of rates for the shipment
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ShipmentRateListItem"
              examples:
                RatesList:
                  summary: Available rates for the shipment
                  value:
                    - uuid: bbbbbbbb-cccc-dddd-eeee-0123456789ab
                      mode: FTL
                      provider_rate_id: quote_example123456
                      transit_time: 2
                      carrier:
                        uuid: cccccccc-dddd-eeee-ffff-0123456789ab
                        name: Example Carrier
                        mc: "123456"
                        dot: "7890123"
                        scac: EXCP
                      rate_lines:
                        - type: all_in
                          quantity: "1.00"
                          unit_price: "1500.00"
                          currency: USD
                      service_level: "Standard"
                      flat_rate: "1500.00"
                      ltl_carrier: null
                      status: available
        "400":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenericError"
          description: Bad request. Invalid query parameters provided.
        "403":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenericError"
          description: Forbidden. Shipper context required or insufficient permissions.
        "401":
          description: Unauthorized – missing or invalid authentication.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UnauthorizedDetail"
        "404":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenericError"
          description: Shipment not found.
        "429":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RateLimitExceededError"
          description: ""
components:
  schemas:
    AccessorialsList:
      type: array
      items:
        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
    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/AppointmentMode'
        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/AppointmentStatusEnum'
          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/AppointmentMode'
        scheduled_window_end:
          type: string
          format: date-time
          nullable: true
        scheduled_window_start:
          type: string
          format: date-time
          nullable: true
    AppointmentConfirmResponse:
      type: object
      properties:
        scheduled_at:
          type: string
          format: date-time
          nullable: true
    AppointmentMode:
      enum:
      - appt
      - fcfs
      type: string
      description: |-
        * `appt` - Appointment
        * `fcfs` - First come, first served
    AppointmentStatusEnum:
      enum:
      - pending
      - requested
      - confirmed
      type: string
      description: |-
        * `pending` - Pending
        * `requested` - Requested
        * `confirmed` - Confirmed
    BlankEnum:
      enum:
      - ''
    BookedRate:
      type: object
      properties:
        rate_lines:
          type: array
          items:
            $ref: '#/components/schemas/OngoingShipmentRateLine'
          title: Booked Rate Lines
          description: Rate lines for booked shipments. This only applies when creating
            booked shipments, i.e., `status` is not `new`.
        provider_rate_id:
          type: string
          description: ID of the provider rate (e.g. Alice Quote ID). This only applies
            when creating booked shipments, i.e., `status` is not `new`.
        asset_carrier:
          allOf:
          - $ref: '#/components/schemas/ShipmentCreateRequestAssetCarrier'
          description: Asset carrier information for booked shipments.
    CountryType:
      enum:
      - USA
      - CAN
      type: string
      description: |-
        * `USA` - United States
        * `CAN` - Canada
    EquipmentTypeEnum:
      enum:
      - DRV
      - RFR
      - FBE
      - SPR
      - CGV
      - STR
      - BTR
      - HOT
      - DRB
      type: string
      description: |-
        * `DRV` - Dry Van
        * `RFR` - Reefer
        * `FBE` - Flatbed
        * `SPR` - Sprinter Van
        * `CGV` - Cargo Van
        * `STR` - Straight Truck
        * `BTR` - Box Truck
        * `HOT` - Hotshot
        * `DRB` - Dry Box
    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
    LoadingTypeEnum:
      enum:
      - live
      - drop
      type: string
      description: |-
        * `live` - Live
        * `drop` - Drop
    MilestoneType:
      enum:
      - check-in
      - check-out
      type: string
      description: |-
        * `check-in` - Check-in
        * `check-out` - Check-out
    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
    MovementEnum:
      enum:
      - inbound
      - outbound
      - transfer
      type: string
      description: |-
        * `inbound` - Inbound
        * `outbound` - Outbound
        * `transfer` - Transfer
    NullEnum:
      enum:
      - null
    OngoingShipmentRateLine:
      type: object
      properties:
        type:
          allOf:
          - $ref: '#/components/schemas/OngoingShipmentRateLineTypeEnum'
          description: The type of the price. For example, it indicates if the component
            is for haul, all_in, fuel_surcharge, extra_charges.
        subtype:
          type: string
          nullable: true
          description: Subtype of the rate line, if applicable
        unit_price:
          type: string
          format: decimal
          pattern: ^-?\d{0,5}(?:\.\d{0,2})?$
          description: Unit price for this specific component in US Dollars. This
            will be multiplied by `quantity`. You can submit a price with 2 decimal
            places and a maximum of 7 digits in total.
        quantity:
          type: integer
          default: 1
          description: The multiplier of the `unit_price`. Default is 1.
      required:
      - type
      - unit_price
    OngoingShipmentRateLineTypeEnum:
      enum:
      - haul
      - fuel_surcharge
      - all_in
      - accessorial
      - from_rate_provider
      type: string
      description: |-
        * `haul` - Haul
        * `fuel_surcharge` - Fuel Surcharge
        * `all_in` - All-In
        * `accessorial` - Accessorial
        * `from_rate_provider` - From Rate Provider
    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
    HazmatClassEnum:
      enum:
      - minor_blast_explosive
      - insensitive_explosive
      - very_insensitive_explosive
      - flammable_gas
      - non_flammable_gas
      - poison_gas
      - combustible_liquid
      - flammable_liquid
      - flammable_solid
      - spontaneously_combustible
      - dangerous_when_wet
      - oxidizer
      - organic_peroxide
      - poisonous_toxic
      - corrosive
      - miscellaneous_dangerous_good
      - explosive_non_specified
      - non_flammable_non_poisonous_or_oxygen_gas
      type: string
      description: |-
        * `minor_blast_explosive` - 1.4 Minor Blast Explosive
        * `insensitive_explosive` - 1.5 Insensitive Explosive
        * `very_insensitive_explosive` - 1.6 Very Insensitive Explosive
        * `flammable_gas` - 2.1 Flammable Gas
        * `non_flammable_gas` - 2.2 Non Flammable Gas
        * `poison_gas` - 2.3 Poison Gas
        * `combustible_liquid` - 3 Combustible Liquid
        * `flammable_liquid` - 3 Flammable Liquid
        * `flammable_solid` - 4.1 Flammable Solid
        * `spontaneously_combustible` - 4.2 Spontaneously Combustible
        * `dangerous_when_wet` - 4.3 Dangerous When Wet
        * `oxidizer` - 5.1 Oxidizer
        * `organic_peroxide` - 5.2 Organic Peroxide
        * `poisonous_toxic` - 6 Poisonous Toxic
        * `corrosive` - 8 Corrosive
        * `miscellaneous_dangerous_good` - 9 Miscellaneous Dangerous Good
        * `explosive_non_specified` - Explosive Non Specified
        * `non_flammable_non_poisonous_or_oxygen_gas` - Non Flammable Non Poisonous or Oxygen Gas
    HazmatPackingGroupEnum:
      enum:
      - group_1
      - group_2
      - group_3
      type: string
      description: |-
        * `group_1` - Group I
        * `group_2` - Group II
        * `group_3` - Group III
    RateLimitExceededError:
      type: object
      description: Error response for rate limit exceeded scenarios.
      properties:
        code:
          type: string
          default: rate_limit_exceeded
        message:
          type: string
          default: Rate limit exceeded. Please try again later.
        extra:
          type: object
          additionalProperties: {}
    ShipmentCancel:
      type: object
      properties:
        reason:
          type: string
          nullable: true
          description: Reason for canceling the shipment.
    ShipmentCharge:
      type: object
      properties:
        uuid:
          type: string
          format: uuid
          readOnly: true
          title: Charge UUID
          description: Unique identifier of the charge created.
      required:
      - uuid
    ShipmentChargeCreate:
      type: object
      properties:
        charge_type_code:
          type: string
          description: Type of the charge you wish to create. It can be any string.
        quantity:
          type: integer
          description: Amount of charges.
        rate:
          type: string
          format: decimal
          pattern: ^-?\d{0,11}(?:\.\d{0,2})?$
          description: Cost of a single charge. Accepts numbers up to 13 digits, including
            the 2 decimal places precision.
        notes:
          type: string
          default: ''
          description: Any notes you might add to the charge being created.
      required:
      - charge_type_code
      - quantity
      - rate
    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 Dry Van, Reefer, and Flatbed
        mode:
          allOf:
          - $ref: '#/components/schemas/ShipmentCreateRequestModeEnum'
          description: |
            Mode of transportation, and the valid modes depend on the Equipment:
            - Dry Van works with FTL, PLT, LTL, VLTL, IMDL
            - Reefer works for FTL, IMDL, DRAY
            - Dry Box works for DRAY
        shipment_reference:
          type: string
          description: Internal customer reference such as the load identifier.
          maxLength: 255
        seal_number:
          type: string
          description: |
            Seal Number. This refers to a tamper-evident seal affixed to the trailer
            doors post-loading to guarantee shipment integrity.
          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.\n        This data is essential if the customer uses\
            \ the Book it Now functionality.\n        "
        trailer_number:
          type: string
          description: The physical trailer identifier used for yard, gate, and tracking operations.
          maxLength: 64
        equipment_length:
          type: string
          nullable: true
          maxLength: 6
          description: |
            Equipment length. Values are accepted with or without apostrophes
            (e.g. `53`, `53'`, or `40' HC`). Stored values omit apostrophes.

            Allowed values for most modes (FTL, PTL, LTL, VLTL, EXP, DRAY):
            `20`, `26`, `32`, `40`, `48`, `52`, `53`.

            For IMDL mode, the following additional values are also allowed:
            `40 HC`, `45 HC`.
        custom_fields:
          type: object
          additionalProperties: true
          nullable: true
          description: Custom key-value fields defined by the shipper. Maximum of 5 fields.
        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.
        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.
        accessorials:
          allOf:
          - $ref: '#/components/schemas/AccessorialsList'
          description: Accessorials indicate the shipment's accessorial services that
            will be executed during the haul.
        status:
          allOf:
          - $ref: '#/components/schemas/ShipmentCreateRequestStatusEnum'
          default: new
          description: Status of the shipment. If not specified, it will be created
            as ‘new’. This field can be used to import shipments that have already
            been booked or are currently in progress.
        booked_rate:
          allOf:
          - $ref: '#/components/schemas/BookedRate'
          description: Rate information for booked shipments. This only applies when
            creating booked shipments, i.e., `status` is not `new`.
        booked_at:
          type: string
          format: date-time
          title: Booked Date
          description: The date when the shipment was booked, in the form YYYY-MM-DDTHH:MM:SSZ.
            This only applies when creating booked shipments, i.e., `status` is not
            `new`.
        carrier_uuid:
          type: string
          format: uuid
          description: The UUID of the carrier that booked the shipment. This only
            applies when creating booked shipments, i.e., `status` is not `new`.
        carrier_ref_number:
          type: string
          title: Carrier Reference Number
          description: Optional field that identifies the shipment in the carrier
            system. This only applies when creating booked shipments, i.e., `status`
            is not `new`.
        hazmat_contact_name:
          type: string
          title: Hazmat Contact Name
          description: The name of the emergency contact person responsible for 
            providing information about the hazardous materials being shipped.
        hazmat_phone_number:
          type: string 
          title: Hazmat Phone Number
          description: The emergency contact phone number for hazmat inquiries.
      required:
      - equipment_type
      - mode
      - shipper_uuid
      - stops
    ShipmentCreateRequestAssetCarrier:
      type: object
      properties:
        name:
          type: string
          title: Asset Carrier Name
          description: Name of the carrier.
          maxLength: 255
        external_id:
          type: string
          title: Asset Carrier External ID
          description: External identifier for the asset carrier.
          maxLength: 255
      required:
      - external_id
      - name
    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
        hazmat:
          type: boolean
          title: Hazmat
          description: Indicates whether the commodity is hazardous.
        hazmat_proper_shipping_name:
          type: string
          title: Hazmat Proper Shipping Name
          description: The Proper Shipping Name for the commodity, required if the commodity is hazardous.
          maxLength: 255
        hazmat_class:
          allOf:
          - $ref: '#/components/schemas/HazmatClassEnum'
          title: Hazmat Class
          description: The Hazmat Class for the commodity, required if the commodity is hazardous.
        hazmat_packing_group:
          allOf:
          - $ref: '#/components/schemas/HazmatPackingGroupEnum'
          title: Hazmat Packing Group
          description: The Hazmat Packing Group for the commodity, required if the commodity is hazardous.
        un_number:
          type: string
          title: UN Number
          description: UN numbers are four-digit numbers that identify hazardous materials, 
            required if the commodity is hazardous.
          maxLength: 30
    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
    ShipmentCreateRequestModeEnum:
      enum:
      - FTL
      - PTL
      - LTL
      - IMDL
      - EXP
      - VLTL
      - DRAY
      type: string
      description: |-
        * `FTL` - Full Truckload
        * `PTL` - Partial Truckload
        * `LTL` - Less-Than-Truckload
        * `IMDL` - Intermodal
        * `EXP` - Expedite
        * `VLTL` - Volume-less-than-Truckload
        * `DRAY` - Drayage
    ShipmentCreateRequestStatusEnum:
      enum:
      - new
      - quoting
      - tendering
      - booked
      - deleted
      - en-route-pickup
      - at-pickup
      - en-route-delivery
      - at-delivery
      - accounting-review
      type: string
      description: |-
        * `new` - new
        * `quoting` - quoting
        * `tendering` - tendering
        * `booked` - booked
        * `deleted` - deleted
        * `en-route-pickup` - en-route-pickup
        * `at-pickup` - at-pickup
        * `en-route-delivery` - en-route-delivery
        * `at-delivery` - at-delivery
        * `accounting-review` - accounting-review
    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/CountryType'
          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:
          allOf:
          - $ref: '#/components/schemas/StopContact'
          description: Point of contact at the facility.
        facility_external_id:
          type: string
          nullable: true
          title: Facility External ID
          description: External identifier of an existing facility. If provided, the
            stop will be linked to the facility with this external ID, and the stop
            address fields will be populated from that facility.
          maxLength: 64
      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
    ShipmentInvoiceResponse:
      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
          nullable: true
          description: Direct URL to access the invoice document.
        uploaded_at:
          type: string
          format: date-time
          description: Timestamp when the invoice was uploaded.
      required:
      - number
      - uploaded_at
      - url
      - uuid
    ShipmentMilestoneStop:
      type: object
      properties:
        index:
          type: integer
          title: Stop index
          description: Index of the stop, starting from 0 (pickup).
      required:
      - index
    ShipmentMilestoneSubmit:
      type: object
      properties:
        type:
          allOf:
          - $ref: '#/components/schemas/MilestoneType'
          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
    StopContact:
      type: object
      properties:
        name:
          type: string
          nullable: true
          description: Contact's name.
          maxLength: 255
        email:
          type: string
          format: email
          nullable: true
          description: Contact's email address.
          maxLength: 255
        phone:
          type: string
          description: Contact's phone number.
          maxLength: 32
        extension:
          type: string
          nullable: true
          description: Contact's phone extension.
          maxLength: 32
      required:
      - phone
    ShipmentListResponse:
      type: object
      required:
        - count
        - results
      properties:
        count:
          type: integer
          description: Total number of shipments matching the filters (before pagination).
        next:
          type: string
          format: uri
          nullable: true
          description: URL to the next page, or null if this is the last page.
        previous:
          type: string
          format: uri
          nullable: true
          description: URL to the previous page, or null if this is the first page.
        results:
          type: array
          items:
            $ref: '#/components/schemas/ShipmentListItem'
    ShipmentListItem:
      type: object
      description: Single shipment in the list.
      properties:
        uuid:
          type: string
          format: uuid
          description: Unique identifier of the shipment.
        bol_number:
          type: string
          nullable: true
          description: Bill of Lading number
        po_numbers:
          type: array
          items:
            type: string
          description: Purchase order numbers
        so_numbers:
          type: array
          items:
            type: string
          description: Sales order numbers
        shipperguide_id:
          type: string
          description: ShipperGuide load identifier
        shipment_reference:
          type: string
          description: Shipper's internal reference
        status:
          type: string
          description: Shipment status (e.g., new, quoting, booked, delivered)
        mode:
          type: string
          description: Transportation mode (e.g., FTL, LTL, PTL)
        equipment_type:
          type: string
          description: Mapped shipment equipment type (e.g. DRV, RFR, FBE).
        stops:
          type: array
          items:
            $ref: '#/components/schemas/ShipmentStop'
        carriers:
          type: array
          items:
            $ref: '#/components/schemas/ShipmentCarrier'
          description: Booked carrier first, then unique carriers from charges.
        handling_units:
          type: array
          items:
            $ref: '#/components/schemas/ShipmentHandlingUnit'
        orders:
          type: array
          items:
            $ref: '#/components/schemas/ShipmentOrder'
        created_at:
          type: string
          format: date-time
          nullable: true
          description: Shipment creation datetime (ISO 8601).
        shipper_custom_fields:
          type: object
          nullable: true
          deprecated: true
          description: |
            Custom key-value fields defined by the shipper.

            **Deprecated:** Use `custom_fields` instead. This field will be removed in a future release.
        custom_fields:
          type: object
          nullable: true
          description: Custom key-value fields defined by the shipper.
        total_approved_cost:
          type: string
          description: Total approved cost amount (decimal string).
          nullable: true
        tags:
          type: array
          items:
            $ref: '#/components/schemas/ShipmentListItemTag'
          description: Tags associated with the shipment.
        booked_rate:
          allOf:
            - $ref: '#/components/schemas/ShipmentBookedRate'
          nullable: true
          description: Rate the shipment is booked under.
    ShipmentStop:
      type: object
      properties:
        address:
          type: string
          nullable: true
        zipcode:
          type: string
          nullable: true
        city:
          type: string
          nullable: true
        state:
          type: string
          nullable: true
        country:
          type: string
          nullable: true
        stop_index:
          type: integer
          nullable: true
        stop_type:
          type: string
          nullable: true
        notes:
          type: string
          nullable: true
        facility:
          $ref: '#/components/schemas/ShipmentFacility'
        planned_date:
          type: string
          format: date
          nullable: true
        appointment:
          $ref: '#/components/schemas/ShipmentAppointment'
        events:
          type: array
          items:
            $ref: '#/components/schemas/ShipmentStopEvent'
    ShipmentFacility:
      type: object
      nullable: true
      properties:
        name:
          type: string
          nullable: true
        instructions:
          type: array
          nullable: true
          items:
            type: string
        address:
          type: string
          nullable: true
        city:
          type: string
          nullable: true
        state:
          type: string
          nullable: true
        country:
          type: string
          nullable: true
        zipcode:
          type: string
          nullable: true
        external_id:
          type: string
          nullable: true
        contact:
          $ref: '#/components/schemas/ShipmentFacilityContact'
    ShipmentStopEvent:
      type: object
      properties:
        type:
          type: string
          nullable: true
        done_via:
          type: string
          nullable: true
        occurred_at:
          type: string
          format: date-time
          nullable: true
    ShipmentCarrier:
      type: object
      properties:
        uuid:
          type: string
          description: Carrier UUID (string).
        name:
          type: string
          nullable: true
        mc:
          type: string
          nullable: true
        dot:
          type: string
          nullable: true
        scac:
          type: string
          nullable: true
    ShipmentBookedRate:
      type: object
      description: Rate the shipment is booked under.
      properties:
        uuid:
          type: string
          format: uuid
          description: Rate UUID (string).
        mode:
          type: string
          nullable: true
          description: Transportation mode (e.g., FTL, LTL, PTL).
        provider_rate_id:
          type: string
          nullable: true
          description: ID of the provider rate (e.g. Alice Quote ID).
        transit_time:
          type: integer
          nullable: true
          description: 'Expected time to deliver the load. Unit: business days.'
    ShipmentBenchmark:
      type: object
      description: |
        Market rate benchmark information for the shipment's lane. Only available to paid shippers.

        Null when the shipment has no linked quote, the shipper is not on a paid plan, or no benchmark rate is available for the lane.

        **About our benchmark**

        1. We use historical data from loads booked on ShipperGuide, as well as from external providers, to provide you with a set of rates to compare with the bids you get from your carriers.
        2. The benchmark is a reference point, and the actual bids you receive may vary based on real-time market conditions, commodity details, accessorials, and other factors.
      properties:
        average:
          type: string
          description: Decimal formatted as string with 2 decimal places.
        lower_bound:
          type: string
          description: Decimal formatted as string with 2 decimal places.
        upper_bound:
          type: string
          description: Decimal formatted as string with 2 decimal places.
        currency:
          type: string
          description: Currency code for the benchmark rates (e.g. USD).
        estimated_on:
          type: string
          format: date
          nullable: true
          description: Date the benchmark datapoint was generated.
        confidence_score:
          type: integer
          minimum: 0
          maximum: 10
          description: Benchmark confidence score, from 0 to 10.
    ShipmentRateLine:
      type: object
      description: Rate line information for a shipment rate.
      properties:
        type:
          type: string
          nullable: true
          description: Type of rate line charge (e.g. all_in, haul, fuel_surcharge).
        quantity:
          type: string
          description: Decimal formatted as string with 2 decimal places.
        unit_price:
          type: string
          description: Decimal formatted as string with 2 decimal places.
        currency:
          type: string
          description: Currency code for the rate line (e.g. USD).
    ShipmentLTLCarrier:
      type: object
      description: LTL carrier information for a rate.
      properties:
        name:
          type: string
          nullable: true
          description: LTL carrier company name.
        external_id:
          type: string
          format: uuid
          description: External carrier identifier.
        scac:
          type: string
          nullable: true
          description: Standard Carrier Alpha Code.
    ShipmentRateListItem:
      type: object
      description: |
        Rate associated with a shipment's quote.
      properties:
        uuid:
          type: string
          format: uuid
          description: Rate UUID.
        mode:
          type: string
          description: Transportation mode (e.g. FTL, LTL).
        provider_rate_id:
          type: string
          nullable: true
          description: Rate identifier from the provider.
        transit_time:
          type: integer
          nullable: true
          description: Transit time in business days.
        carrier:
          $ref: "#/components/schemas/ShipmentCarrier"
        rate_lines:
          type: array
          items:
            $ref: "#/components/schemas/ShipmentRateLine"
        service_level:
          type: string
          nullable: true
          description: Service level for the rate.
        flat_rate:
          type: string
          description: All-in price proposed by the carrier, formatted as string with 2 decimal places.
        ltl_carrier:
          allOf:
            - $ref: "#/components/schemas/ShipmentLTLCarrier"
          nullable: true
        status:
          type: string
          nullable: true
          description: |
            Current status of the rate (e.g. pending, available, tendered, booked, expired, rejected).
    ShipmentHandlingUnit:
      type: object
      properties:
        quantity:
          type: integer
        type:
          type: string
          nullable: true
        height:
          type: string
          nullable: true
        length:
          type: string
          nullable: true
        width:
          type: string
          nullable: true
        weight:
          type: string
          nullable: true
        stackable:
          type: boolean
        turnable:
          type: boolean
        po_numbers:
          type: array
          items:
            type: string
        so_numbers:
          type: array
          items:
            type: string
        pickup_stop_index:
          type: integer
          nullable: true
        delivery_stop_index:
          type: integer
          nullable: true
        max_temperature:
          type: string
          nullable: true
        commodities:
          type: array
          items:
            $ref: '#/components/schemas/ShipmentCommodity'
    ShipmentCommodity:
      type: object
      properties:
        description:
          type: string
        package_type:
          type: string
          nullable: true
        quantity:
          type: integer
        freight_class:
          type: string
          nullable: true
        nmfc_code:
          type: string
        hazmat:
          type: boolean
        hazmat_class:
          type: string
          nullable: true
        un_number:
          type: string
        hazmat_proper_shipping_name:
          type: string
        hazmat_packing_group:
          type: string
          nullable: true
    ShipmentOrder:
      type: object
      properties:
        custom_fields:
          type: object
          nullable: true
        movement:
          type: string
          nullable: true
        po_number:
          type: string
          nullable: true
        so_number:
          type: string
          nullable: true
        external_id:
          type: string
          nullable: true
        primary_ref:
          type: string
          nullable: true
        ship_with:
          type: string
          nullable: true
        supplier:
          type: object
          properties:
            external_id:
              type: string
              nullable: true
        pickup:
          type: object
          properties:
            facility:
              $ref: '#/components/schemas/ShipmentFacility'
            earliest:
              type: string
              format: date-time
              nullable: true
            latest:
              type: string
              format: date-time
              nullable: true
        delivery:
          type: object
          properties:
            facility:
              $ref: '#/components/schemas/ShipmentFacility'
            earliest:
              type: string
              format: date-time
              nullable: true
            latest:
              type: string
              format: date-time
              nullable: true
        items:
          type: array
          items:
            $ref: '#/components/schemas/ShipmentOrderItem'
        fulfillments:
          type: array
          items:
            $ref: '#/components/schemas/ShipmentFulfillment'
    ShipmentOrderItem:
      type: object
      description: Order item information
      properties:
        commodity:
          type: string
          nullable: true
        country_of_origin:
          type: string
          nullable: true
        custom_package_type:
          type: string
          nullable: true
        description:
          type: string
          nullable: true
        freight_class:
          type: string
          nullable: true
        item_id:
          type: string
          nullable: true
        line_number:
          type: integer
          nullable: true
        max_temperature:
          type: number
          nullable: true
        nmfc_code:
          type: string
          nullable: true
        package_type:
          type: string
          nullable: true
        quantity:
          type: integer
          nullable: true
        upc:
          type: string
          nullable: true
        weight:
          type: number
          nullable: true
    ShipmentFulfillment:
      type: object
      properties:
        ref_number:
          type: string
          nullable: true
        external_id:
          type: string
          nullable: true
          description: Unique external reference for the fulfillment from your system.
        equipment_type:
          type: string
          nullable: true
        notes:
          type: string
          nullable: true
          description: Free-text field for additional information about the order or shipping order. Visible to all users with access to the order. Supports alphanumeric characters and common punctuation.
          example: "Fragile items - handle with care. Delivery dock closes at 5 PM."
        total_cargo_value:
          type: string
          format: decimal
          pattern: ^\d{0,13}(?:\.\d{0,2})?$
          nullable: true
          description: The total declared monetary value of the cargo being shipped. Used for insurance calculations and carrier liability limits. Value is in USD unless otherwise specified. Must be a positive decimal value with up to 2 decimal places.
          example: "25000.00"
        handling_units:
          type: array
          items:
            type: object
            properties:
              height:
                type: string
                nullable: true
              width:
                type: string
                nullable: true
              length:
                type: string
                nullable: true
              stackable:
                type: boolean
              turnable:
                type: boolean
              quantity:
                type: integer
              type:
                type: string
                nullable: true
              shipped_items:
                type: array
                items:
                  type: object
                  properties:
                    line_number:
                      type: integer
                    shipped_count:
                      type: integer
                    shipped_weight:
                      type: number
    ShipmentAppointment:
      type: object
      nullable: true
      properties:
        confirmation_number:
          type: string
          nullable: true
        misscheduling_reason:
          nullable: true
          oneOf:
          - $ref: '#/components/schemas/MisschedulingReasonEnum'
          - $ref: '#/components/schemas/BlankEnum'
          - $ref: '#/components/schemas/NullEnum'
        misscheduling_note:
          type: string
          nullable: true
        status:
          $ref: '#/components/schemas/AppointmentStatusEnum'
        mode:
          $ref: '#/components/schemas/AppointmentMode'
        loading_type:
          $ref: '#/components/schemas/LoadingTypeEnum'
        scheduled_window_start:
          type: string
          format: date-time
          nullable: true
        scheduled_window_end:
          type: string
          format: date-time
          nullable: true
    ShipmentFacilityContact:
      type: object
      properties:
        name:
          type: string
          nullable: true
          description: Contact's name.
          maxLength: 255
        email:
          type: string
          format: email
          nullable: true
          description: Contact's email address.
          maxLength: 255
        phone:
          type: string
          description: Contact's phone number.
          maxLength: 32
        extension:
          type: string
          nullable: true
          description: Contact's phone extension.
          maxLength: 32
    ShipmentListItemTag:
      type: object
      properties:
        uuid:
          type: string
          format: uuid
          description: Unique identifier of the tag.
        name:
          type: string
          description: Tag name
        color:
          type: string
          description: Tag color (e.g. hex such as `#000000`).
    ShipmentDetail:
      type: object
      description: Full shipment information returned by the detail endpoint
      properties:
        uuid:
          type: string
          format: uuid
          description: Unique identifier of the shipment
        shipper:
          $ref: "#/components/schemas/ShipmentShipperDetail"
        mode:
          type: string
          description: Transportation mode (e.g., FTL, LTL, PTL)
        status:
          type: string
          description: Shipment status (e.g., new, quoting, booked, delivered)
        bol_number:
          type: string
          nullable: true
          description: Bill of Lading number
        shipperguide_id:
          type: string
          description: ShipperGuide load identifier
        shipment_reference:
          type: string
          description: Shipper's internal reference
        po_numbers:
          type: array
          items:
            type: string
          description: Purchase order numbers
        so_numbers:
          type: array
          items:
            type: string
          description: Sales order numbers
        notes:
          type: string
          description: Notes from the quote
        equipment_type:
          type: string
          description: Mapped shipment equipment type (e.g. DRV, RFR, FBE).
        equipment_length:
          type: string
          description: Equipment length
        equipment_requirements:
          $ref: "#/components/schemas/ShipmentEquipmentRequirements"
        tags:
          type: array
          items:
            $ref: "#/components/schemas/ShipmentTag"
        shipper_custom_fields:
          type: object
          additionalProperties: true
          description: |
            Custom fields defined by the shipper.

            **Deprecated:** Use `custom_fields` instead. This field will be removed in a future release.
          nullable: true
          deprecated: true
        custom_fields:
          type: object
          additionalProperties: true
          description: Custom fields defined by the shipper
          nullable: true
        target_rate:
          type: string
          description: Target rate amount
          nullable: true
        mileage:
          type: integer
          description: Total mileage
          nullable: true
        rate:
          type: string
          description: Approved charges total amount
        booked_rate:
          allOf:
            - $ref: "#/components/schemas/ShipmentBookedRate"
          nullable: true
          description: Rate the shipment is booked under.
        benchmark:
          allOf:
            - $ref: "#/components/schemas/ShipmentBenchmark"
          nullable: true
        carriers:
          type: array
          items:
            $ref: "#/components/schemas/ShipmentCarrier"
          description: Booked carrier first, then unique carriers from charges.
        stops:
          type: array
          items:
            $ref: "#/components/schemas/ShipmentStop"
        handling_units:
          type: array
          items:
            $ref: "#/components/schemas/ShipmentHandlingUnit"
        charges:
          type: array
          items:
            $ref: "#/components/schemas/ShipmentDetailCharge"
        invoices:
          type: array
          items:
            $ref: "#/components/schemas/ShipmentDetailInvoice"
        attachments:
          type: array
          items:
            $ref: "#/components/schemas/ShipmentDetailAttachment"
          description: All available documents related to the shipment (e.g. bill of lading, ratecon, proof of pickup, proof of delivery, invoices, etc.)
        public_tracking_link:
          type: string
          description: Public tracking URL
          nullable: true
        trailer_number:
          type: string
          nullable: true
        seal_number:
          type: string
          nullable: true
        hazmat:
          type: boolean
          description: Whether the shipment contains hazardous materials
        hazmat_contact_name:
          type: string
          nullable: true
        hazmat_phone_number:
          type: string
          nullable: true
        orders:
          type: array
          items:
            $ref: '#/components/schemas/ShipmentOrder'
    ShipmentShipperDetail:
      type: object
      properties:
        uuid:
          type: string
          format: uuid
          description: Shipper UUID
    ShipmentEquipmentRequirements:
      type: object
      description: Equipment-specific requirements
      properties:
        temperature:
          type: string
          nullable: true
        unit:
          type: string
          nullable: true
          description: Temperature unit (e.g., fahrenheit, celsius)
        tarp_size:
          type: string
          nullable: true
        tarp_type:
          type: string
          nullable: true
        equipment_subtypes:
          type: array
          items:
            type: string
          nullable: true
        requires_dunnage:
          type: boolean
          nullable: true
        requires_tarp:
          type: boolean
          nullable: true
    ShipmentTag:
      type: object
      properties:
        name:
          type: string
          description: Tag name
    ShipmentDetailCharge:
      type: object
      properties:
        uuid:
          type: string
          format: uuid
        status:
          type: string
        unit:
          type: string
          nullable: true
        quantity:
          type: integer
          nullable: true
        notes:
          type: string
        created_at:
          type: string
          format: date-time
          nullable: true
        amount_per_unit:
          type: string
          nullable: true
        total:
          type: string
          nullable: true
        carrier:
          $ref: "#/components/schemas/ShipmentDetailCarrierShort"
          nullable: true
        type:
          $ref: "#/components/schemas/ShipmentDetailChargeType"
          nullable: true
        invoice:
          type: string
          format: uuid
          nullable: true
          description: Invoice UUID when charge is invoiced
    ShipmentDetailCarrierShort:
      type: object
      description: Simplified carrier reference (uuid only in charges)
      properties:
        uuid:
          type: string
          format: uuid
    ShipmentDetailChargeType:
      type: object
      properties:
        uuid:
          type: string
          format: uuid
        name:
          type: string
        code:
          type: string
        is_accessorial:
          type: boolean
    ShipmentDetailInvoice:
      type: object
      properties:
        uuid:
          type: string
          format: uuid
        number:
          type: string
          nullable: true
        uploaded_at:
          type: string
          format: date-time
          nullable: true
        due_date:
          type: string
          nullable: true
        charges:
          type: array
          items:
            type: string
            format: uuid
          description: List of charge UUIDs included in this invoice
    ShipmentDetailAttachment:
      type: object
      properties:
        attachment_name:
          type: string
          description: File name
        attachment_type:
          type: string
          description: Attachment type
        attachment_uuid:
          type: string
          format: uuid
        attachment_url:
          type: string
          description: Pre-signed URL to access the file
          nullable: true
        attachment_stop_index:
          type: integer
          nullable: true
          description: Stop index when attachment is stop-specific
        attachment_status:
          type: string
          nullable: true
          description: Status of the attachment (for attachments that needs approval from the shipper)
  securitySchemes:
    jwt:
      type: http
      scheme: bearer
      bearerFormat: JWT
servers:
- url: https://api.loadsmart.com/api/v3
  description: Production environment
