Shipments

Submit a shipment

Changed on Oct 7, 2026

Take a draft shipment open and create the loads its carriers are assigned to.

This is the step between POST /shipments and giving a load a carrier. A shipment is created in draft; submitting runs the same routine the TMS itself uses, so the loads it produces match what the UI would have made.

Pass autoSubmit: true on create to have this run as part of creation instead of as a second call.

What happens

The shipment's orders move out of draft
Loads are created for the order's stops
The updated shipment is returned, loads included

Prerequisites

The shipment must still be in draft

post/shipments/{id}/submit

Request

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

Response

Shipment submitted 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 7, 20262cd6ecfbeb82 Revision changes
- 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
  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
  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
- 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
Oct 1, 202666fb538125ab Revision changes
- info
  endpoint added

Operation history