--- title: "Create a shipment" method: POST path: "/shipments" tags: ["Shipments"] --- # Create a shipment `POST /shipments` 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. ## Request body - ShipmentInput - `customer` union, required — Reference to another resource by either ID or client key (used in create/update requests) - object - `id` string, uuid, required — Resource UUID - `key` string — Client-defined reference ID - object - `id` string, uuid — Resource UUID - `key` string, required — Client-defined reference ID - `customerRep` union — Reference to another resource by either ID or client key (used in create/update requests) - object - `id` string, uuid, required — Resource UUID - `key` string — Client-defined reference ID - object - `id` string, uuid — Resource UUID - `key` string, required — Client-defined reference ID - `orders` OrderInput[], required — Orders to create (at least one required) - `mode` 'TL' | 'LTL' | 'AIR' | 'OCEAN' | 'RAIL' | 'INTERMODAL' | 'DRAYAGE', required — 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 - `stops` OrderStopInput[], required — At least origin and destination stops - `type` 'PICKUP' | 'DELIVERY' | 'CROSS_DOCK', required — Type of stop - `location` union — Reference to another resource by either ID or client key (used in create/update requests) - object - `id` string, uuid, required — Resource UUID - `key` string — Client-defined reference ID - object - `id` string, uuid — Resource UUID - `key` string, required — Client-defined reference ID - `address` AddressInput — Address data for creating a new location - `line1` string, required — Primary street address line - `line2` string — 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 — Latitude coordinate - `longitude` string — Longitude coordinate - `isAirportOrAirbase` boolean — Whether this location is an airport or airbase - `isConstructionOrUtilitySite` boolean — Whether this location is a construction or utility site - `isSmartyValidated` boolean — Whether address has been validated by SmartyStreets - `obeysDst` boolean — Whether this location observes daylight saving time - `cityId` string, uuid — Reference to standardized city record (internal use) - `requestedStartDate` string, date — Requested start date for the stop - `requestedEndDate` string, date — Requested end date for the stop - `requestedStartTime` string — Requested start time (HH:MM format) - `requestedEndTime` string — Requested end time (HH:MM format) - `appointmentRequired` boolean — Whether an appointment is required - `notes` string — Special instructions for the stop - `freight` OrderFreightInput — Freight details for an order - `handlingUnitQuantity` integer — Number of handling units - `handlingUnitType` 'PALLET' | 'SKID' | 'CARTON' | 'CRATE' | 'DRUM' | 'BUNDLE' | 'ROLL' | 'BAG' | 'TOTE' | 'OTHER' — Type of handling unit - `weight` number — Total weight in pounds - `volume` number — Total volume in cubic feet - `length` number — Length in inches - `width` number — Width in inches - `height` number — Height in inches - `commodityDescription` string — Description of the commodity - `hazmat` boolean — Whether freight is hazardous materials - `stackable` boolean — Whether freight is stackable - `equipment` ResourceReferenceInput[] — Equipment types required - union — Reference to another resource by either ID or client key (used in create/update requests) - object - `id` string, uuid, required — Resource UUID - `key` string — Client-defined reference ID - object - `id` string, uuid — Resource UUID - `key` string, required — Client-defined reference ID - `references` object[] — Reference numbers for the order - `type` string, required — Reference type (e.g., BOL_NUMBER, PO_NUMBER) - `value` string, required — Reference value - `specialRequirements` ResourceReferenceInput[] — Special requirements (e.g., liftgate, team drivers) - union — Reference to another resource by either ID or client key (used in create/update requests) - object - `id` string, uuid, required — Resource UUID - `key` string — Client-defined reference ID - object - `id` string, uuid — Resource UUID - `key` string, required — Client-defined reference ID - `loads` LoadInput[] — Optional loads to create - `mode` 'TL' | 'LTL' | 'AIR' | 'OCEAN' | 'RAIL' | 'INTERMODAL' | 'DRAYAGE', required — 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 - `orderStopIds` string[] — Order stop IDs to include in this load - `carrier` LoadCarrierInput - `carrier` union, required — Reference to another resource by either ID or client key (used in create/update requests) - object - `id` string, uuid, required — Resource UUID - `key` string — Client-defined reference ID - object - `id` string, uuid — Resource UUID - `key` string, required — Client-defined reference ID - `contact` union — Reference to another resource by either ID or client key (used in create/update requests) - object - `id` string, uuid, required — Resource UUID - `key` string — Client-defined reference ID - object - `id` string, uuid — Resource UUID - `key` string, required — Client-defined reference ID - `charges` object[] - `chargeCode` union, required — Reference to another resource by either ID or client key (used in create/update requests) - object - `id` string, uuid, required — Resource UUID - `key` string — Client-defined reference ID - object - `id` string, uuid — Resource UUID - `key` string, required — Client-defined reference ID - `description` string - `amount` number, required - `quantity` number - `driverName` string - `driverPhone` string - `truckNumber` string - `trailerNumber` string - `services` ServiceInput[] — Optional services to create - `vendor` union, required — Reference to another resource by either ID or client key (used in create/update requests) - object - `id` string, uuid, required — Resource UUID - `key` string — Client-defined reference ID - object - `id` string, uuid — Resource UUID - `key` string, required — Client-defined reference ID - `vendorContact` union — Reference to another resource by either ID or client key (used in create/update requests) - object - `id` string, uuid, required — Resource UUID - `key` string — Client-defined reference ID - object - `id` string, uuid — Resource UUID - `key` string, required — Client-defined reference ID - `serviceType` 'DRAYAGE' | 'CUSTOMS_CLEARANCE' | 'WAREHOUSING' | 'CROSS_DOCK' | 'TRANSLOAD' | 'FUMIGATION' | 'INSPECTION' | 'DOCUMENTATION' | 'INSURANCE' | 'CARGO_HANDLING' | 'OTHER', required — Type of service. - `DRAYAGE`: Port/rail drayage - `CUSTOMS_CLEARANCE`: Customs brokerage - `WAREHOUSING`: Warehouse storage - `CROSS_DOCK`: Cross-dock handling - `TRANSLOAD`: Transloading service - `FUMIGATION`: Cargo fumigation - `INSPECTION`: Cargo inspection - `DOCUMENTATION`: Documentation handling - `INSURANCE`: Cargo insurance - `CARGO_HANDLING`: General cargo handling - `OTHER`: Other service type - `description` string - `charges` object[] - `chargeCode` union, required — Reference to another resource by either ID or client key (used in create/update requests) - object - `id` string, uuid, required — Resource UUID - `key` string — Client-defined reference ID - object - `id` string, uuid — Resource UUID - `key` string, required — Client-defined reference ID - `description` string - `amount` number, required - `quantity` number - `scheduledDate` string, date - `referenceNumber` string ## Response `201` Shipment created 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 - `422` — Validation error - invalid field values --- [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/revisions/c44e5e7a4256/schema)