---
title: "Cancel a shipment"
method: POST
path: "/shipments/{id}/cancel"
tags: ["Shipments"]
---

# Cancel a shipment

`POST /shipments/{id}/cancel`

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

## Path parameters

- `id` string, required

## Query parameters

- `by` 'id' | 'key'

## Request body

- CancelShipmentRequest — Request body for canceling a shipment
  - `reason` string — Reason for cancellation

## Response `200`

Shipment canceled successfully

- Shipment
  - `id` string, uuid, required
  - `key` string, 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
  - `customer` CustomerReference — Enhanced reference to a customer resource (returned in responses). Includes full customer details in addition to id/key. Note: Does NOT include nested references (paymentTerm, contacts, etc.) to prevent recursion. Maximum nesting depth: 1 level.
    - `id` string, uuid, required — Customer UUID
    - `key` string, nullable — Client-defined reference ID if set
    - `name` string, required — Customer company name
    - `friendlyId` string, required — Human-readable customer identifier
    - `status` 'PROSPECT' | 'ACTIVE' | 'INACTIVE' | 'CHURNED', required — Customer status
    - `phoneNumber` string, nullable — Primary phone number
    - `website` string, nullable — Customer website URL
    - `createdAt` string, date-time, required — When the customer was created
    - `updatedAt` string, date-time, required — When the customer was last updated
    - `deletedAt` string, date-time, nullable — When the customer was soft deleted (null if active)
  - `customerRep` UserReference — Enhanced reference to a user resource (returned in responses). Includes full user details in addition to id/key. Note: Does NOT include nested references (teams, etc.) to prevent recursion. Maximum nesting depth: 1 level.
    - `id` string, uuid, required — User UUID
    - `key` string, nullable — Client-defined reference ID if set
    - `email` string, email, required — User's email address
    - `name` string, nullable — User's full name
    - `phone` string, nullable — User's phone number
    - `phoneExt` string, nullable — Phone extension
    - `status` 'PENDING' | 'ACTIVE' | 'INACTIVE', required — User account status
    - `avatarId` string, uuid, nullable — Profile avatar document ID
    - `createdAt` string, date-time, required — When the user was created
    - `updatedAt` string, date-time, required — When the user was last updated
    - `deletedAt` string, date-time, nullable — When the user was soft deleted (null if active)
  - `orders` Order[] — Orders in this shipment
    - `id` string, uuid
    - `key` string, nullable — Friendly order ID
    - `mode` 'TL' | 'LTL' | 'AIR' | 'OCEAN' | 'RAIL' | 'INTERMODAL' | 'DRAYAGE' — Transportation mode. - `TL`: Full Truckload - `LTL`: Less than Truckload - `AIR`: Air freight - `OCEAN`: Ocean freight - `RAIL`: Rail freight - `INTERMODAL`: Intermodal (multiple modes) - `DRAYAGE`: Drayage/cartage
    - `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' — 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
    - `billingStatus` 'DOCS_NEEDED' | 'NOT_READY_TO_INVOICE' | 'READY_TO_INVOICE' | 'INVOICED' | 'PARTIALLY_PAID' | 'PAID' — Billing status for the order (AR side). - `DOCS_NEEDED`: Waiting for delivery documents - `NOT_READY_TO_INVOICE`: Not ready to invoice - `READY_TO_INVOICE`: Ready to generate invoice - `INVOICED`: Invoice generated and sent - `PARTIALLY_PAID`: Partial payment received - `PAID`: Fully paid
    - `stops` OrderStop[] — Flattened stops array
      - `id` string, uuid
      - `type` 'PICKUP' | 'DELIVERY' | 'CROSS_DOCK'
      - `sequence` integer — Stop order in the route
      - `location` ResourceReference — Reference to another resource (returned in responses)
        - `id` string, uuid, required — Resource UUID
        - `key` string, nullable — Client-defined reference ID if set
      - `address` Address — Physical address/location details (nested, without id). This is an embedded object representing a Location record. The id is managed internally and not exposed in the API.
        - `line1` string, required — Primary street address line
        - `line2` string, nullable — Secondary address line (suite, floor, etc.)
        - `city` string, required — City name
        - `country` string, required — Country name or code
        - `market` string, required — Market or region identifier
        - `latitude` string, nullable — Latitude coordinate
        - `longitude` string, nullable — Longitude coordinate
        - `isAirportOrAirbase` boolean, required — Whether this location is an airport or airbase
        - `isConstructionOrUtilitySite` boolean, required — Whether this location is a construction or utility site
        - `isSmartyValidated` boolean, required — Whether address has been validated by SmartyStreets
        - `obeysDst` boolean, required — Whether this location observes daylight saving time
        - `cityId` string, uuid, nullable — Reference to standardized city record (internal use)
      - `requestedStartDate` string, date, nullable
      - `requestedEndDate` string, date, nullable
      - `requestedStartTime` string, nullable
      - `requestedEndTime` string, nullable
      - `actualArrival` string, date-time, nullable
      - `actualDeparture` string, date-time, nullable
      - `appointmentRequired` boolean
      - `notes` string, nullable
    - `freight` OrderFreight
      - `handlingUnitQuantity` integer, nullable
      - `handlingUnitType` string, nullable
      - `weight` number, nullable — Weight in pounds
      - `volume` number, nullable — Volume in cubic feet
      - `length` number, nullable
      - `width` number, nullable
      - `height` number, nullable
      - `commodityDescription` string, nullable
      - `hazmat` boolean
      - `stackable` boolean
    - `references` OrderReference[]
      - `id` string, uuid
      - `type` string — Reference type (e.g., BOL_NUMBER)
      - `value` string — Reference value
    - `charges` OrderCharge[]
      - `id` string, uuid
      - `chargeCode` ResourceReference — Reference to another resource (returned in responses)
        - `id` string, uuid, required — Resource UUID
        - `key` string, nullable — Client-defined reference ID if set
      - `description` string, nullable
      - `amount` number
      - `quantity` number
      - `rate` number, nullable
    - `equipment` ResourceReference[]
      - `id` string, uuid, required — Resource UUID
      - `key` string, nullable — Client-defined reference ID if set
    - `specialRequirements` ResourceReference[]
      - `id` string, uuid, required — Resource UUID
      - `key` string, nullable — Client-defined reference ID if set
    - `mileage` number, nullable
    - `totalRevenue` number, nullable — Sum of all charges
    - `createdAt` string, date-time
    - `updatedAt` string, date-time, nullable
  - `loads` LoadSummary[] — Loads for carrier execution
    - `id` string, uuid
    - `key` string, nullable
    - `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' — 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
    - `mode` 'TL' | 'LTL' | 'AIR' | 'OCEAN' | 'RAIL' | 'INTERMODAL' | 'DRAYAGE' — Transportation mode. - `TL`: Full Truckload - `LTL`: Less than Truckload - `AIR`: Air freight - `OCEAN`: Ocean freight - `RAIL`: Rail freight - `INTERMODAL`: Intermodal (multiple modes) - `DRAYAGE`: Drayage/cartage
    - `carriers` LoadCarrierSummary[] — Flattened carriers array
      - `id` string, uuid
      - `carrier` CarrierReference — Enhanced reference to a carrier resource (returned in responses). Includes full carrier details in addition to id/key. Note: Does NOT include nested references (contacts, etc.) to prevent recursion. Maximum nesting depth: 1 level.
        - `id` string, uuid, required — Carrier UUID
        - `key` string, nullable — Client-defined reference ID if set
        - `name` string, required — Carrier company name
        - `phoneNumber` string, nullable — Primary phone number
        - `email` string, email, nullable — Primary email address
        - `createdAt` string, date-time, required — When the carrier was created
        - `updatedAt` string, date-time, required — When the carrier was last updated
        - `deletedAt` string, date-time, nullable — When the carrier was soft deleted (null if active)
      - `status` 'ACTIVE' | 'TONU' | 'BOUNCED'
      - `bookedAt` string, date-time, nullable
      - `dispatchedAt` string, date-time, nullable
      - `totalCost` number, nullable
    - `totalCost` number, nullable
  - `services` ServiceSummary[] — Vended services
    - `id` string, uuid
    - `key` string, nullable
    - `vendor` VendorReference — Enhanced reference to a vendor profile. Includes full vendor details in addition to id/key.
      - `id` string, uuid, required — Vendor UUID
      - `key` string, nullable — Client-defined reference ID if set
      - `friendlyId` string, required — Human-readable vendor identifier
      - `name` string, required — Vendor legal name
      - `email` string, email, nullable — Primary email address
      - `phone` string, nullable — Primary phone number
      - `status` string, nullable — Vendor status
      - `currency` string, nullable — Preferred currency code (ISO 4217)
      - `createdAt` string, date-time, required — When the vendor was created
      - `updatedAt` string, date-time, required — When the vendor was last updated
    - `serviceType` string
    - `status` 'ACTIVE' | 'AWAITING_INVOICE' | 'INVOICE_IN_REVIEW' | 'APPROVED_TO_PAY' | 'PAID' | 'CANCELED'
    - `cost` number, nullable
  - `totalRevenue` number, nullable — Sum of all order charges
  - `totalCost` number, nullable — Sum of all load and service costs
  - `margin` number, nullable — Revenue minus cost
  - `marginPercent` number, nullable — Margin as percentage of revenue
  - `createdAt` string, date-time, required
  - `updatedAt` string, date-time, nullable
  - `deliveredAt` string, date-time, nullable

## Other responses

- `400` — Bad request - invalid input
- `401` — Unauthorized - invalid or missing access token
- `404` — Resource not found
- `409` — Cannot cancel - shipment is delivered or already canceled

---

[API](https://skmtc.net/mvmnt/apis/mvmnt-api.md) · [All operations](https://skmtc.net/mvmnt/apis/mvmnt-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mvmnt/mvmnt-api/versions/c44e5e7a4256/schema)