Shipments

Update a shipment's status

Changed on

Move a shipment to another status, as the TMS status picker does.

What happens

  • Shipment status changes to the requested one
  • Its orders, loads and services follow, as they do in the TMS: for example, a delivered shipment's loads move to awaiting invoice and its orders to docs needed

Prerequisites

  • The status must be one of allowedStatuses from GET /shipments/{id}/status. Which ones depend on the current status, the mode, and whether the shipment has been invoiced.
  • An LTL shipment is dispatched through its carrier dispatch, not here.
  • Canceling and un-canceling have their own endpoints.
post/shipments/{id}/status

Request

  • Base URL: https://api.mvmnt.io/v1
  • URL: https://api.mvmnt.io/v1/shipments/{id}/status
  • 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

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

Response

Shipment status updated

idstring uuid required
friendlyIdstring required

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

keystring 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
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