# Submit a shipment

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

Endpoint: POST /shipments/{id}/submit
Version: 1.1.0
Security: BearerAuth

## Path parameters:

  - `id` (string, required)
    Resource ID (UUID) or client key
    Example: "550e8400-e29b-41d4-a716-446655440000"

## Query parameters:

  - `by` (string)
    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.
    Enum: "id", "key"

## Response 200 fields (application/json):

  - `id` (string, required)
    Example: "550e8400-e29b-41d4-a716-446655440000"

  - `friendlyId` (string, required)
    Human-readable shipment ID (e.g., "SHP-12345")
    Example: "SHP-12345"

  - `key` (string,null)
    Client-defined reference identifier for this shipment
    Example: "my-shipment-001"

  - `status` (string, 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
    Enum: "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"

  - `customer` (object)
    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.

  - `customer.id` (string, required)
    Customer UUID
    Example: "550e8400-e29b-41d4-a716-446655440000"

  - `customer.key` (string,null)
    Client-defined reference ID if set
    Example: "ERP-CUSTOMER-ACME"

  - `customer.name` (string, required)
    Customer company name
    Example: "Acme Manufacturing Corp"

  - `customer.friendlyId` (string, required)
    Human-readable customer identifier
    Example: "A123456"

  - `customer.status` (string, required)
    Customer status
    Enum: "NEW", "CONTACTED", "QUALIFIED", "QUOTED", "NURTURING", "PENDING", "ACTIVE", "INACTIVE", "BLOCKED", "CLOSED"

  - `customer.phoneNumber` (string,null)
    Primary phone number
    Example: "+1-555-123-4567"

  - `customer.website` (string,null)
    Customer website URL
    Example: "https://acme-manufacturing.com"

  - `customer.createdAt` (string, required)
    When the customer was created
    Example: "2025-01-15T10:00:00Z"

  - `customer.updatedAt` (string, required)
    When the customer was last updated
    Example: "2025-01-15T14:30:00Z"

  - `customer.deletedAt` (string,null)
    When the customer was soft deleted (null if active)

  - `customerRep` (object)
    Customer representative

  - `customerRep.id` (string, required)
    User UUID
    Example: "550e8400-e29b-41d4-a716-446655440000"

  - `customerRep.email` (string, required)
    User's email address
    Example: "john.doe@example.com"

  - `customerRep.name` (string,null)
    User's full name
    Example: "John Doe"

  - `customerRep.phone` (string,null)
    User's phone number
    Example: "+1-555-123-4567"

  - `customerRep.phoneExt` (string,null)
    Phone extension
    Example: "123"

  - `customerRep.status` (string, required)
    User account status
    Enum: "PENDING", "ACTIVE", "INACTIVE"

  - `customerRep.avatarId` (string,null)
    Profile avatar document ID
    Example: "7c9e6679-7425-40de-944b-e07fc1f90ae7"

  - `customerRep.createdAt` (string, required)
    When the user was created
    Example: "2025-01-15T10:00:00Z"

  - `customerRep.updatedAt` (string, required)
    When the user was last updated
    Example: "2025-01-15T14:30:00Z"

  - `customerRep.deletedAt` (string,null)
    When the user was soft deleted (null if active)

  - `orders` (array)
    Orders in this shipment

  - `orders.friendlyId` (string)
    Human-readable order ID (e.g., "ORD-12345")

  - `orders.key` (string,null)
    Client-defined reference identifier for this order

  - `orders.mode` (string)
    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
    Enum: "FTL", "TL", "LTL", "PTL", "RLTL", "BULK", "AIR", "OCEAN", "RAIL", "INTERMODAL", "DRAYAGE", "AUTO", "EXPEDITED_AIR", "EXPEDITED_GROUND"

  - `orders.billingStatus` (string)
    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
    Enum: "DOCS_NEEDED", "NOT_READY_TO_INVOICE", "READY_TO_INVOICE", "INVOICED", "PAID"

  - `orders.stops` (array)
    Flattened stops array

  - `orders.stops.id` (string)
    The stop as it belongs to this order. Two orders sharing a stop each
see their own id here.

  - `orders.stops.stopId` (string)
    The underlying stop, shared by every order that visits it. This is
the id LoadInput.stopIds takes when splitting a shipment across
loads.

  - `orders.stops.type` (string)
    Enum: "PICK", "DROP"

  - `orders.stops.sequence` (integer)
    Stop order in the route

  - `orders.stops.location` (object)
    Reference to another resource (returned in responses)

  - `orders.stops.location.id` (string, required)
    Resource UUID

  - `orders.stops.address` (object)
    Full address from the stop's linked location. Absent when the stop
has no linked shipper location.

  - `orders.stops.address.line1` (string, required)
    Primary street address line
    Example: "123 Main St"

  - `orders.stops.address.line2` (string,null)
    Secondary address line (suite, floor, etc.)
    Example: "Suite 400"

  - `orders.stops.address.city` (string, required)
    City name
    Example: "Chicago"

  - `orders.stops.address.state` (string,null)
    State or province code
    Example: "IL"

  - `orders.stops.address.zipCode` (string,null)
    Postal / ZIP code
    Example: "60601"

  - `orders.stops.address.country` (string, required)
    Country name or code
    Example: "USA"

  - `orders.stops.address.market` (string, required)
    Market or region identifier
    Example: "CHI"

  - `orders.stops.address.latitude` (string,null)
    Latitude coordinate
    Example: "41.8781"

  - `orders.stops.address.longitude` (string,null)
    Longitude coordinate
    Example: "-87.6298"

  - `orders.stops.address.isAirportOrAirbase` (boolean, required)
    Whether this location is an airport or airbase

  - `orders.stops.address.isConstructionOrUtilitySite` (boolean, required)
    Whether this location is a construction or utility site

  - `orders.stops.address.isSmartyValidated` (boolean, required)
    Whether address has been validated by SmartyStreets
    Example: true

  - `orders.stops.address.obeysDst` (boolean, required)
    Whether this location observes daylight saving time
    Example: true

  - `orders.stops.address.cityId` (string,null)
    Reference to standardized city record (internal use)

  - `orders.stops.postalCode` (string,null)
    Set when the stop was placed by postal code rather than by a
location.

  - `orders.stops.city` (object,null)
    Set when the stop was placed in a city from the reference catalog.

  - `orders.stops.city.name` (string)

  - `orders.stops.city.stateProvince` (string)

  - `orders.stops.airportCode` (string,null)
    Set when the stop was placed at an airport terminal.

  - `orders.stops.requestedStartDate` (string,null)

  - `orders.stops.requestedEndDate` (string,null)

  - `orders.stops.requestedStartTime` (string,null)

  - `orders.stops.requestedEndTime` (string,null)

  - `orders.stops.actualArrival` (string,null)

  - `orders.stops.actualDeparture` (string,null)

  - `orders.stops.appointmentRequired` (boolean)

  - `orders.stops.notes` (string,null)

  - `orders.freight` (object)

  - `orders.freight.handlingUnitQuantity` (integer,null)

  - `orders.freight.handlingUnitType` (string,null)

  - `orders.freight.weight` (number,null)
    Weight in pounds

  - `orders.freight.volume` (number,null)
    Volume in cubic feet

  - `orders.freight.length` (number,null)

  - `orders.freight.width` (number,null)

  - `orders.freight.height` (number,null)

  - `orders.freight.commodityDescription` (string,null)

  - `orders.freight.hazmat` (boolean)

  - `orders.freight.hazmatClass` (string,null)

  - `orders.freight.hazmatSubClass` (string,null)

  - `orders.freight.hazmatGroup` (string,null)

  - `orders.freight.hazmatUnNumber` (string,null)

  - `orders.freight.stackable` (boolean)

  - `orders.freight.highValue` (boolean)

  - `orders.freight.commodity` (boolean)

  - `orders.freight.weightUnit` (string,null)

  - `orders.freight.measurementUnit` (string,null)

  - `orders.freight.packages` (array)
    Individual package lines. LTL pricing is quoted off these rather than
off the freight totals. At most 100 are returned per freight; a
shipment carrying more is beyond what this representation expands.

  - `orders.freight.packages.description` (string,null)

  - `orders.freight.packages.quantity` (integer,null)

  - `orders.freight.packages.caseQuantity` (integer,null)

  - `orders.freight.packages.freightClass` (string,null)

  - `orders.freight.packages.nmfc` (string,null)

  - `orders.freight.packages.nmfcSub` (string,null)

  - `orders.freight.packages.weight` (number,null)

  - `orders.references` (array)

  - `orders.references.type` (string)
    Reference type (e.g., BOL_NUMBER)

  - `orders.references.value` (string)
    Reference value

  - `orders.charges` (array)

  - `orders.charges.chargeCodeId` (integer,null)
    Charge code id. Resolve code/name via the reference-data charge-codes endpoint.

  - `orders.charges.amount` (number)

  - `orders.charges.rate` (number,null)

  - `orders.equipment` (array)
    Equipment ids. Resolve names via the reference-data equipment endpoint.

  - `orders.specialRequirements` (array)
    Special-requirement ids. Resolve names via the reference-data endpoint.

  - `orders.mileage` (number,null)

  - `orders.totalRevenue` (number,null)
    Sum of all charges

  - `orders.createdAt` (string)

  - `orders.updatedAt` (string,null)

  - `loads` (array)
    Loads for carrier execution

  - `loads.friendlyId` (string)
    Human-readable load ID (e.g., "LD-12345")

  - `loads.key` (string,null)
    Client-defined reference identifier for this load

  - `loads.carriers` (array)
    Flattened carriers array

  - `loads.carriers.carrier` (object)
    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.

  - `loads.carriers.carrier.id` (string, required)
    Carrier UUID
    Example: "550e8400-e29b-41d4-a716-446655440000"

  - `loads.carriers.carrier.name` (string, required)
    Carrier company name
    Example: "Swift Transportation"

  - `loads.carriers.carrier.email` (string,null)
    Primary email address
    Example: "dispatch@swifttrans.com"

  - `loads.carriers.carrier.createdAt` (string, required)
    When the carrier was created
    Example: "2025-01-15T10:00:00Z"

  - `loads.carriers.carrier.updatedAt` (string, required)
    When the carrier was last updated
    Example: "2025-01-15T14:30:00Z"

  - `loads.carriers.carrier.deletedAt` (string,null)
    When the carrier was soft deleted (null if active)

  - `loads.carriers.status` (string)
    Enum: "ACTIVE", "TONU", "BOUNCED"

  - `loads.carriers.bookedAt` (string,null)

  - `loads.carriers.dispatchedAt` (string,null)

  - `loads.carriers.removedAt` (string,null)
    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.

  - `loads.carriers.totalCost` (number,null)

  - `services` (array)
    Vended services

  - `services.key` (string,null)

  - `services.vendor` (object)
    Enhanced reference to a vendor profile.
Includes full vendor details in addition to id/key.

  - `services.vendor.id` (string, required)
    Vendor UUID
    Example: "550e8400-e29b-41d4-a716-446655440000"

  - `services.vendor.friendlyId` (string, required)
    Human-readable vendor identifier
    Example: "V123456"

  - `services.vendor.name` (string, required)
    Vendor legal name
    Example: "ABC Warehouse Services"

  - `services.vendor.phone` (string,null)
    Primary phone number
    Example: "+1-555-123-4567"

  - `services.vendor.status` (string,null)
    Vendor status
    Example: "ACTIVE"

  - `services.vendor.currency` (string,null)
    Preferred currency code (ISO 4217)
    Example: "USD"

  - `services.vendor.createdAt` (string, required)
    When the vendor was created
    Example: "2025-01-15T10:00:00Z"

  - `services.vendor.updatedAt` (string, required)
    When the vendor was last updated
    Example: "2025-01-15T14:30:00Z"

  - `services.cost` (number,null)

  - `totalRevenue` (number,null)
    Sum of all order charges

  - `totalCost` (number,null)
    Sum of all load and service costs

  - `margin` (number,null)
    Revenue minus cost

  - `marginPercent` (number,null)
    Margin as percentage of revenue

  - `deliveredAt` (string,null)

## Response 400 fields (application/problem+json):

  - `type` (string, required)
    URI identifying the problem type
    Example: "https://api.mvmnt.io/problems/not-found"

  - `title` (string, required)
    Short summary of the problem type
    Example: "Not Found"

  - `status` (integer, required)
    HTTP status code
    Example: 404

  - `detail` (string)
    Explanation specific to this occurrence
    Example: "Customer not found: 550e8400-e29b-41d4-a716-446655440000"

  - `instance` (string)
    The request path that produced the problem
    Example: "/v1/customers/550e8400-e29b-41d4-a716-446655440000"

  - `code` (string)
    Machine-readable error code, when one applies

  - `errors` (array)
    Per-field problems, when the error concerns specific fields

  - `errors.field` (string, required)
    The field the message refers to
    Example: "/required"

  - `errors.message` (string, required)
    What is wrong with it
    Example: "missing property 'status'"

## Response 401 fields (application/problem+json):

  - `type` (string, required)
    URI identifying the problem type
    Example: "https://api.mvmnt.io/problems/not-found"

  - `title` (string, required)
    Short summary of the problem type
    Example: "Not Found"

  - `status` (integer, required)
    HTTP status code
    Example: 404

  - `detail` (string)
    Explanation specific to this occurrence
    Example: "Customer not found: 550e8400-e29b-41d4-a716-446655440000"

  - `instance` (string)
    The request path that produced the problem
    Example: "/v1/customers/550e8400-e29b-41d4-a716-446655440000"

  - `code` (string)
    Machine-readable error code, when one applies

  - `errors` (array)
    Per-field problems, when the error concerns specific fields

  - `errors.field` (string, required)
    The field the message refers to
    Example: "/required"

  - `errors.message` (string, required)
    What is wrong with it
    Example: "missing property 'status'"

## Response 404 fields (application/problem+json):

  - `type` (string, required)
    URI identifying the problem type
    Example: "https://api.mvmnt.io/problems/not-found"

  - `title` (string, required)
    Short summary of the problem type
    Example: "Not Found"

  - `status` (integer, required)
    HTTP status code
    Example: 404

  - `detail` (string)
    Explanation specific to this occurrence
    Example: "Customer not found: 550e8400-e29b-41d4-a716-446655440000"

  - `instance` (string)
    The request path that produced the problem
    Example: "/v1/customers/550e8400-e29b-41d4-a716-446655440000"

  - `code` (string)
    Machine-readable error code, when one applies

  - `errors` (array)
    Per-field problems, when the error concerns specific fields

  - `errors.field` (string, required)
    The field the message refers to
    Example: "/required"

  - `errors.message` (string, required)
    What is wrong with it
    Example: "missing property 'status'"

## Response 409 fields (application/problem+json):

  - `type` (string, required)
    URI identifying the problem type
    Example: "https://api.mvmnt.io/problems/not-found"

  - `title` (string, required)
    Short summary of the problem type
    Example: "Not Found"

  - `status` (integer, required)
    HTTP status code
    Example: 404

  - `detail` (string)
    Explanation specific to this occurrence
    Example: "Customer not found: 550e8400-e29b-41d4-a716-446655440000"

  - `instance` (string)
    The request path that produced the problem
    Example: "/v1/customers/550e8400-e29b-41d4-a716-446655440000"

  - `code` (string)
    Machine-readable error code, when one applies

  - `errors` (array)
    Per-field problems, when the error concerns specific fields

  - `errors.field` (string, required)
    The field the message refers to
    Example: "/required"

  - `errors.message` (string, required)
    What is wrong with it
    Example: "missing property 'status'"