Shipments

Create a shipment

Changed on Oct 16, 2026

Create a new shipment with its orders.

Loads and services are not part of this payload. A load covers a subset of the shipment's stops, which only have ids once the orders exist, so loads are created against the shipment afterwards:

Loads: POST /loads
Services: POST /services

Required fields

customer: Reference to the customer
mode: How the shipment moves — it belongs to the shipment, not to its individual orders
orders: At least one order with stops

What gets created

Shipment record
Order(s) with stops, freight, and charges

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

Base URL: https://api.mvmnt.io/v1
URL: https://api.mvmnt.io/v1/shipments
Auth: HTTP bearer

Request body

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
BULK: Bulk truckload freight
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

autoSubmitboolean

Submit the shipment as part of creating it, instead of following up with POST /shipments/{id}/submit. A shipment is created in draft either way; submitting is what takes it open and creates its loads.

Response

Shipment created successfully

idstring uuid required

friendlyIdstring required

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

keystring nullable

Client-defined reference identifier for this shipment

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

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",
  "friendlyId": "SHP-12345",
  "key": "my-shipment-001",
  "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",
            "state": "IL",
            "zipCode": "60601",
            "country": "USA",
            "market": "CHI",
            "latitude": "41.8781",
            "longitude": "-87.6298",
            "isSmartyValidated": true,
            "obeysDst": true
          }
        }
      ]
    }
  ],
  "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"
      }
    }
  ]
}

Changes

Oct 16, 2026a67a66657930 Revision changes
- breaking
  request property /// was restricted to a list of enum values
- breaking
  request property /// was restricted to a list of enum values
- breaking
  request property ///// was restricted to a list of enum values
- breaking
  request property ///// was restricted to a list of enum values
- breaking
  request property ///// was restricted to a list of enum values
- breaking
  request property /// was restricted to a list of enum values
- info
  added the new 100 enum value to the request property /////
- info
  added the new 110 enum value to the request property /////
- info
  added the new 125 enum value to the request property /////
- info
  added the new 150 enum value to the request property /////
- info
  added the new 175 enum value to the request property /////
- info
  added the new 200 enum value to the request property /////
- info
  added the new 250 enum value to the request property /////
- info
  added the new 300 enum value to the request property /////
- info
  added the new 400 enum value to the request property /////
- info
  added the new 50 enum value to the request property /////
- info
  added the new 500 enum value to the request property /////
- info
  added the new 55 enum value to the request property /////
- info
  added the new 60 enum value to the request property /////
- info
  added the new 65 enum value to the request property /////
- info
  added the new 70 enum value to the request property /////
- info
  added the new 77.5 enum value to the request property /////
- info
  added the new 85 enum value to the request property /////
- info
  added the new 92.5 enum value to the request property /////
- info
  added the new CM enum value to the request property ///
- info
  added the new CM enum value to the request property /////
- info
  added the new CORROSIVE enum value to the request property ///
- info
  added the new EXPLOSIVES enum value to the request property ///
- info
  added the new FLAMMABLE_COMBUSTIBLE_LIQUID enum value to the request property ///
- info
  added the new FLAMMABLE_SOLID_COMBUSTIBLE_DANGEROUS_WHEN_WET enum value to the request property ///
- info
  added the new FT enum value to the request property ///
- info
  added the new FT enum value to the request property /////
- info
  added the new GASES enum value to the request property ///
- info
  added the new IN enum value to the request property ///
- info
  added the new IN enum value to the request property /////
- info
  added the new KG enum value to the request property /////
- info
  added the new KG enum value to the request property ///
- info
  added the new LB enum value to the request property /////
- info
  added the new LB enum value to the request property ///
- info
  added the new M enum value to the request property ///
- info
  added the new M enum value to the request property /////
- info
  added the new MISCELLANEOUS enum value to the request property ///
- info
  added the new OXIDIZER_ORGANIC_PEROXIDE enum value to the request property ///
- info
  added the new POISON_INHALATION_HAZARD enum value to the request property ///
- info
  added the new RADIOACTIVE enum value to the request property ///
- info
  added the new SHORT_TON enum value to the request property /////
- info
  added the new SHORT_TON enum value to the request property ///
- info
  added the new TONNE enum value to the request property /////
- info
  added the new TONNE enum value to the request property ///
Oct 7, 20262cd6ecfbeb82 Revision changes
- breaking
  the response's body type changed from object to no type for status
- breaking
  removed the required property from the response with the status
- breaking
  removed the required property from the response with the status
- breaking
  removed the required property from the response with the status
- breaking
  removed the required property from the response with the status
- breaking
  removed the required property from the response with the status
- breaking
  removed the required property from the response with the status
- breaking
  removed the required property from the response with the status
- breaking
  removed the required property from the response with the status
- breaking
  removed the required property from the response with the status
- warning
  added the new DROP enum value to the //// response property for the response status
- warning
  added the new PICK enum value to the //// response property for the response status
- info
  added the new DROP enum value to the request property ////
- info
  added the new PICK enum value to the request property ////
- info
  added subschema #2 to the response body allOf list for the response status
- info
  media type application/json was changed to a more specific media type application/problem+json for the response status
- info
  media type application/json was changed to a more specific media type application/problem+json for the response status
- info
  media type application/json was changed to a more specific media type application/problem+json for the response status
- info
  media type application/json was changed to a more specific media type application/problem+json for the response status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  removed the DELIVERY enum value from the //// response property for the response status
- info
  removed the PICKUP enum value from the //// response property for the response status
- info
  added the required property to the response with the status
- info
  added the required property to the response with the status
- info
  added the required property to the response with the status
- info
  added the required property to the response with the status
- info
  added the required property to the response with the status
- info
  added the required property to the response with the status
- info
  added the required property to the response with the status
- info
  added the required property to the response with the status
- info
  added the required property to the response with the status

Operation history (7 revisions)