--- title: "Filter shipments" method: POST path: "/shipments/filter" tags: ["Shipments"] --- # Filter shipments `POST /shipments/filter` Search for shipments using filter criteria. Each row in the response carries the fully nested shipment payload (orders with stops, freight, references, charges; loads with carriers). With a large `pageSize`, responses can be sizable — use a smaller page size if you only need scalar fields. ## Common Filters - Active shipments: `{ "filter": { "status": { "notIn": ["DELIVERED", "CANCELED"] } } }` - Delivered today: `{ "filter": { "deliveredAt": { "greaterThanOrEqualTo": "2025-01-15T00:00:00Z" } } }` - By customer: `{ "filter": { "customerId": { "equalTo": "uuid" } } }` ## Request body - ShipmentFilterRequest - `filter` ShipmentFilter - `id` UUIDFilter — Filter options for UUID fields (all operations) - `equalTo` string, uuid — Exact match - `notEqualTo` string, uuid — Not equal to - `in` string[] — Matches any UUID in the array - `notIn` string[] — Does not match any UUID in the array - `isNull` boolean — Field is null (true) or not null (false) - `key` StringFilter — Filter options for string fields - `equalTo` string — Exact match - `notEqualTo` string — Not equal to - `in` string[] — Matches any value in the array - `notIn` string[] — Does not match any value in the array - `includes` string — Contains substring (case-insensitive) - `notIncludes` string — Does not contain substring (case-insensitive) - `startsWith` string — Starts with prefix (case-insensitive) - `notStartsWith` string — Does not start with prefix (case-insensitive) - `endsWith` string — Ends with suffix (case-insensitive) - `notEndsWith` string — Does not end with suffix (case-insensitive) - `isNull` boolean — Field is null (true) or not null (false) - `status` ShipmentStatusFilter - `equalTo` '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' | 'CONSOLIDATED' — 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 - `CONSOLIDATED`: Merged into a consolidated shipment - `notEqualTo` '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' | 'CONSOLIDATED' — 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 - `CONSOLIDATED`: Merged into a consolidated shipment - `in` ShipmentLifecycleStatus[] - `notIn` ShipmentLifecycleStatus[] - `customerId` UUIDFilter — Filter options for UUID fields (all operations) - `equalTo` string, uuid — Exact match - `notEqualTo` string, uuid — Not equal to - `in` string[] — Matches any UUID in the array - `notIn` string[] — Does not match any UUID in the array - `isNull` boolean — Field is null (true) or not null (false) - `customerRepId` UUIDFilter — Filter options for UUID fields (all operations) - `equalTo` string, uuid — Exact match - `notEqualTo` string, uuid — Not equal to - `in` string[] — Matches any UUID in the array - `notIn` string[] — Does not match any UUID in the array - `isNull` boolean — Field is null (true) or not null (false) - `createdAt` DatetimeFilter — Filter options for datetime fields - `equalTo` string, date-time — Exact match - `notEqualTo` string, date-time — Not equal to - `lessThan` string, date-time — Before this datetime - `lessThanOrEqualTo` string, date-time — On or before this datetime - `greaterThan` string, date-time — After this datetime - `greaterThanOrEqualTo` string, date-time — On or after this datetime - `isNull` boolean — Field is null (true) or not null (false) - `updatedAt` DatetimeFilter — Filter options for datetime fields - `equalTo` string, date-time — Exact match - `notEqualTo` string, date-time — Not equal to - `lessThan` string, date-time — Before this datetime - `lessThanOrEqualTo` string, date-time — On or before this datetime - `greaterThan` string, date-time — After this datetime - `greaterThanOrEqualTo` string, date-time — On or after this datetime - `isNull` boolean — Field is null (true) or not null (false) - `deliveredAt` DatetimeFilter — Filter options for datetime fields - `equalTo` string, date-time — Exact match - `notEqualTo` string, date-time — Not equal to - `lessThan` string, date-time — Before this datetime - `lessThanOrEqualTo` string, date-time — On or before this datetime - `greaterThan` string, date-time — After this datetime - `greaterThanOrEqualTo` string, date-time — On or after this datetime - `isNull` boolean — Field is null (true) or not null (false) - `and` ShipmentFilter[] - `or` ShipmentFilter[] - `not` ShipmentFilter — recursive - `pageSize` integer - `cursor` string ## Response `200` Shipments matching filter criteria - object - `data` Shipment[], required - `id` string, uuid, required - `friendlyId` string, required — Human-readable shipment ID (e.g., "SHP-12345") - `key` string, nullable — Client-defined reference identifier for this shipment - `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' | 'CONSOLIDATED', 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 - `CONSOLIDATED`: Merged into a consolidated shipment - `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` 'NEW' | 'CONTACTED' | 'QUALIFIED' | 'QUOTED' | 'NURTURING' | 'PENDING' | 'ACTIVE' | 'INACTIVE' | 'BLOCKED' | 'CLOSED', 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 - `friendlyId` string — Human-readable order ID (e.g., "ORD-12345") - `key` string, nullable — Client-defined reference identifier for this order - `mode` 'FTL' | 'TL' | 'LTL' | 'PTL' | 'RLTL' | 'AIR' | 'OCEAN' | 'RAIL' | 'INTERMODAL' | 'DRAYAGE' | 'AUTO' | 'EXPEDITED_AIR' | 'EXPEDITED_GROUND' — Transportation mode. Optional on write — a shipment or load created without one is stored with no mode, the same as one created in the TMS. - `FTL`: Full Truckload — the value the TMS stores and always returns - `TL`: legacy spelling of `FTL`, still accepted on write, never returned - `LTL`: Less than Truckload - `PTL`: Partial Truckload - `RLTL`: Retail LTL - `AUTO`: Auto transport - `EXPEDITED_AIR`: Expedited air - `EXPEDITED_GROUND`: Expedited ground - `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' | 'CONSOLIDATED' — 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 - `CONSOLIDATED`: Merged into a consolidated shipment - `billingStatus` 'DOCS_NEEDED' | 'NOT_READY_TO_INVOICE' | 'READY_TO_INVOICE' | 'INVOICED' | '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 - `PAID`: Fully paid - `stops` OrderStop[] — Flattened stops array - `id` string, uuid - `type` 'PICKUP' | 'DELIVERY' - `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 - `state` string, nullable — State or province code - `zipCode` string, nullable — Postal / ZIP code - `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 - `chargeCodeId` integer, nullable — Charge code id. Resolve code/name via the reference-data charge-codes endpoint. - `description` string, nullable - `amount` number - `quantity` number - `rate` number, nullable - `equipment` string[] — Equipment ids. Resolve names via the reference-data equipment endpoint. - `specialRequirements` string[] — Special-requirement ids. Resolve names via the reference-data endpoint. - `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 - `friendlyId` string — Human-readable load ID (e.g., "LD-12345") - `key` string, nullable — Client-defined reference identifier for this load - `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' | 'CONSOLIDATED' — 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 - `CONSOLIDATED`: Merged into a consolidated shipment - `mode` 'FTL' | 'TL' | 'LTL' | 'PTL' | 'RLTL' | 'AIR' | 'OCEAN' | 'RAIL' | 'INTERMODAL' | 'DRAYAGE' | 'AUTO' | 'EXPEDITED_AIR' | 'EXPEDITED_GROUND' — Transportation mode. Optional on write — a shipment or load created without one is stored with no mode, the same as one created in the TMS. - `FTL`: Full Truckload — the value the TMS stores and always returns - `TL`: legacy spelling of `FTL`, still accepted on write, never returned - `LTL`: Less than Truckload - `PTL`: Partial Truckload - `RLTL`: Retail LTL - `AUTO`: Auto transport - `EXPEDITED_AIR`: Expedited air - `EXPEDITED_GROUND`: Expedited ground - `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 - `removedAt` string, date-time, nullable — When this carrier was removed from the load (bounce/TONU). Removed carriers stay in the array as history, but their charges are NOT included in the load's `totalCost`. - `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 - `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 - `pagination` PaginationInfo, required - `pageSize` integer, required — Number of items per page - `hasNextPage` boolean, required — Whether there are more pages - `hasPreviousPage` boolean — Whether there are previous pages - `endCursor` string, nullable — Cursor for the next page (null if no next page) ## Other responses - `400` — Bad request - invalid input - `401` — Unauthorized - invalid or missing access token - `422` — Validation error - invalid field values --- [API](https://skmtc.dev/mvmnt/apis/mvmnt-api.md) · [All operations](https://skmtc.dev/mvmnt/apis/mvmnt-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/mvmnt/mvmnt-api/revisions/7af4e91459ca/schema)