Cancel a shipment

Cancel a shipment.

What happens

Shipment status is set to CANCELED
All orders are canceled
All loads are canceled
All services are canceled

Prerequisites

Shipment must not already be delivered or canceled

idstring required

Resource ID (UUID) or client key

by'id' | 'key'

Specify lookup type for faster retrieval. If omitted, defaults to looking up by ID first, then falls back to client key if not found. Use by=key when you know you're providing a client key for best performance.

Request body

reasonstring

Reason for cancellation

Response

Shipment canceled successfully

idstring uuid required

keystring required

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

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"
      }
    }
  ]
}

v1