Shipments

Update a shipment

Changed on Oct 16, 2026

Update shipment fields.

Note: To update orders, loads, or services, use their respective endpoints:

Orders: Updates happen via order-specific endpoints
Loads: PATCH /loads/{id}
Services: PATCH /services/{id}

patch/shipments/{id}

Request

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

Path parameters

idstring required

Resource ID (UUID) or client key

Query parameters

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

Response

Shipment updated 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
- warning
  removed 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 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)