Sign in

v1

latestOpenAPI 3.1.0Proprietary2026-08-06177398877.4 KB
Shipments

Create a shipment

Create a new shipment with orders, loads, and services.

Required fields

  • customer: Reference to the customer
  • orders: At least one order with stops and mode

What gets created

  • Shipment record
  • Order(s) with stops, freight, and charges
  • Optionally: Load(s) and Service(s)

Relationship to Quotes

If you have a Quote, use POST /quotes/{id}/convert-to-shipment instead. Direct shipment creation is for cases without a quote.

post/shipments

Request body

Example request

{
  "orders": [
    {
      "stops": [
        {
          "address": {
            "line1": "123 Main St",
            "line2": "Suite 400",
            "city": "Chicago",
            "country": "USA",
            "market": "CHI",
            "latitude": "41.8781",
            "longitude": "-87.6298",
            "isSmartyValidated": true,
            "obeysDst": true
          }
        }
      ]
    }
  ]
}

Response

Shipment created successfully

idstring uuid required
keystring required

Human-readable shipment ID (e.g., "SHP-12345")

status'DRAFT' | 'TENDER_PENDING' | 'ON_HOLD' | 'PLANNING' | 'SELECTED' | 'BOOKED' | 'DISPATCHED' | 'LOADING' | 'PICKED_UP' | 'IN_TRANSIT' | 'UNLOADING' | 'ARRIVED_AT_DELIVERY_TERMINAL' | 'OUT_FOR_DELIVERY' | 'RECOVERED' | 'DELIVERED' | 'CANCELED' | 'TENDER_REJECTED' required

Current status of the shipment lifecycle.

Pre-transit:

  • DRAFT: Shipment being created
  • TENDER_PENDING: Awaiting carrier tender acceptance
  • TENDER_REJECTED: Carrier rejected the tender
  • ON_HOLD: Shipment temporarily paused
  • PLANNING: Being planned/scheduled
  • SELECTED: Carrier selected
  • BOOKED: Carrier confirmed booking
  • DISPATCHED: Dispatched to carrier

In-transit:

  • LOADING: Loading at pickup
  • PICKED_UP: Picked up
  • IN_TRANSIT: In transit
  • UNLOADING: Unloading at delivery
  • ARRIVED_AT_DELIVERY_TERMINAL: At delivery terminal (LTL)
  • OUT_FOR_DELIVERY: Out for final delivery
  • RECOVERED: Shipment has been recovered

Final:

  • DELIVERED: Delivered
  • CANCELED: Canceled
totalRevenuenumber nullable

Sum of all order charges

totalCostnumber nullable

Sum of all load and service costs

marginnumber nullable

Revenue minus cost

marginPercentnumber nullable

Margin as percentage of revenue

createdAtstring date-time required
updatedAtstring date-time nullable
deliveredAtstring date-time nullable

Example response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "key": "SHP-12345",
  "customer": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "key": "ERP-CUSTOMER-ACME",
    "name": "Acme Manufacturing Corp",
    "friendlyId": "A123456",
    "status": "ACTIVE",
    "phoneNumber": "+1-555-123-4567",
    "website": "https://acme-manufacturing.com",
    "createdAt": "2025-01-15T10:00:00Z",
    "updatedAt": "2025-01-15T14:30:00Z"
  },
  "customerRep": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "key": "ERP-USER-12345",
    "email": "john.doe@example.com",
    "name": "John Doe",
    "phone": "+1-555-123-4567",
    "phoneExt": "123",
    "status": "ACTIVE",
    "avatarId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "createdAt": "2025-01-15T10:00:00Z",
    "updatedAt": "2025-01-15T14:30:00Z"
  },
  "orders": [
    {
      "stops": [
        {
          "location": {
            "id": "550e8400-e29b-41d4-a716-446655440000",
            "key": "ERP-USER-12345"
          },
          "address": {
            "line1": "123 Main St",
            "line2": "Suite 400",
            "city": "Chicago",
            "country": "USA",
            "market": "CHI",
            "latitude": "41.8781",
            "longitude": "-87.6298",
            "isSmartyValidated": true,
            "obeysDst": true
          }
        }
      ],
      "charges": [
        {
          "chargeCode": {
            "id": "550e8400-e29b-41d4-a716-446655440000",
            "key": "ERP-USER-12345"
          }
        }
      ],
      "equipment": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "key": "ERP-USER-12345"
        }
      ],
      "specialRequirements": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "key": "ERP-USER-12345"
        }
      ]
    }
  ],
  "loads": [
    {
      "carriers": [
        {
          "carrier": {
            "id": "550e8400-e29b-41d4-a716-446655440000",
            "key": "ERP-CARRIER-SWIFT",
            "name": "Swift Transportation",
            "phoneNumber": "+1-555-987-6543",
            "email": "dispatch@swifttrans.com",
            "createdAt": "2025-01-15T10:00:00Z",
            "updatedAt": "2025-01-15T14:30:00Z"
          }
        }
      ]
    }
  ],
  "services": [
    {
      "vendor": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "key": "ERP-VENDOR-ABC-001",
        "friendlyId": "V123456",
        "name": "ABC Warehouse Services",
        "email": "billing@abcwarehouse.com",
        "phone": "+1-555-123-4567",
        "status": "ACTIVE",
        "currency": "USD",
        "createdAt": "2025-01-15T10:00:00Z",
        "updatedAt": "2025-01-15T14:30:00Z"
      }
    }
  ]
}