Skip to content
API Reference/
/
Mark shipment ready to in...

MVMNT API (1.0.0)

The MVMNT API enables you to automate freight brokerage workflows by integrating directly with our Transportation Management System.

Postman setup guide: API Clients.

Authentication

OAuth 2.0 client credentials flow. See Authentication Guide for details.

Token Endpoint

POST https://api.mvmnt.io/oauth2/token

Request

Headers:

Content-Type: application/x-www-form-urlencoded

Body Parameters:

grant_type=client_credentials
client_id=YOUR_CLIENT_ID
client_secret=YOUR_CLIENT_SECRET

Example Request

curl -X POST https://api.mvmnt.io/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

Success Response

Status: 200 OK

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Response Fields:

  • access_token: JWT Bearer token to use for API requests
  • token_type: Always Bearer
  • expires_in: Token lifetime in seconds (3600 = 1 hour)

Idempotency

Mutating requests (POST, PATCH, DELETE) accept an optional Idempotency-Key header (up to 255 characters). Retrying a request with the same key and the same body returns the original result instead of repeating the operation; reusing a key with a different body fails. Keys are scoped to your organization — keys chosen by other tenants can never collide with yours. Use a stable identifier from your system (for example your own record id plus the action) rather than a random value per attempt.

Download OpenAPI description
openapi.json
openapi.yaml
openapi-3.0.yaml (legacy tooling)
Postman Collection
Postman Environment — Demo
Postman Environment — Production
Overview
URL
https://docs.mvmnt.io
MVMNT Support
support@mvmnt.io
License
Proprietary
Languages
Servers
Production
https://api.mvmnt.io/v1
Demo (non-production)
https://api.demo.mvmnt.io/v1

Carriers

Carrier management operations

Operations

Carrier Contacts

Carrier contact management operations

Operations

Carrier Factors

Carrier factor (factoring company) management operations

Operations

Carrier Payment Methods

Carrier payment method management operations

Operations

Companies

Company management operations

Operations

Credit Memos

AR credit memo management operations. Credit memos represent customer credits that can be applied to invoices.

Operations

Bills

AP bill management operations. Bills represent carrier and vendor invoices to be paid.

Operations

Bill Payments

AP bill payment management operations. Bill payments record payments made to carriers and vendors.

Operations

Customers

Customer management operations

Operations

Customer Contacts

Customer contact management operations

Operations

Documents

Document management operations. Documents are files (PDFs, images) that can be attached to orders, loads, or services.

Operations

Invoices

AR invoice management operations. Invoices represent customer billing for shipment services.

Operations

Loads

Load management operations. Loads represent carrier execution - which carrier is moving the freight.

Operations

Locations

Location management operations

Operations

Location Contacts

Location contact management operations

Operations

Payment Terms

Payment term management operations

Operations

Reference Data

Read-only catalogs (equipment, charge codes, special requirements) referenced by id from other resources.

Every catalog also answers on its short top-level path, so GET /v1/charge-codes and GET /v1/reference-data/charge-codes are the same endpoint. The documented /reference-data/* form is canonical — it keeps the catalogs grouped here as more are added (port codes, cities, zip codes) — and the short form is a convenience alias.

Operations

Payments

AR payment management operations. Payments represent received customer payments applied to invoices.

Operations

Quotes

Quote management operations. Quotes are pricing requests/responses that can be converted to shipments.

Operations

Saved Searches

Saved search management operations

Operations

Services

Service (vended service) management operations. Services represent non-carrier vendor work (drayage, customs, warehousing).

Operations

Shipments

Shipment tracking and management operations. Shipments contain orders, loads, and services.

Operations

Get tracking link

Request

Search for shipments by reference field values (BOL #, PRO #, MAWB #, etc.) and return tracking information.

Usage

  1. Provide an array of search queries in the searches field
  2. Optionally filter which reference field types to search using referenceFields
  3. Results are returned in the same order as input searches
  4. If no match is found, the result contains only the original query (other fields are null)

Matching Behavior

  • Searches are case-insensitive
  • If multiple shipments match a query, the most recently created shipment is returned
  • If referenceFields is omitted, all reference field types are searched

Example Use Cases

  • Customer portal: Look up shipment status by BOL or PRO number
  • EDI integration: Validate shipment references before sending updates
  • Bulk status check: Query multiple shipments in a single request

Rate Limits

  • Maximum 100 searches per request
  • Standard API rate limits apply (see Rate Limiting documentation)
Security
BearerAuth
Bodyapplication/jsonrequired
searchesArray of objects(ShipmentTrackSearch)[ 1 .. 100 ] itemsrequired

Array of search queries. Results are returned in the same order as the input searches. Maximum 100 searches per request.

Example: [{"query":"MAWB123456"},{"query":"BOL789"}]
querystring[ 4 .. 255 ] charactersrequired

Reference value to search for (minimum 4 characters)

Example: "MAWB123456"
referenceFieldsArray of strings(ShipmentReferenceField)

Optional filter for reference field types to search. If omitted, searches all reference field types.

Common use: limit search to specific field types for faster results or to avoid false matches across different reference types.

Items Enum"BOL_NUMBER""PICKUP_NUMBER""DELIVERY_NUMBER""PURCHASE_ORDER_NUMBER""GENERAL_LEDGER_CODE""CUSTOMER_REFERENCE_NUMBER""PRO_NUMBER""ITEM_IDENTIFICATION""PART_NUMBER""ACCOUNT_NUMBER"
Example: ["MASTER_AIRWAYBILL_NUMBER","BOL_NUMBER"]
curl -i -X POST \
  https://api.mvmnt.io/v1/shipments/track \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "searches": [
      {
        "query": "MAWB123456"
      }
    ]
  }'

Responses

Track results returned successfully

Bodyapplication/json
resultsArray of objects(ShipmentTrackResult)required

Array of tracking results in the same order as input searches.

Each result contains the original query plus matching shipment data. If no match is found, only the query field is populated (all other fields are null).

If multiple shipments match a query, the most recently created shipment is returned.

Example: [{"query":"MAWB123456","id":"550e8400-e29b-41d4-a716-446655440000","key":"SHIP-001","friendlyId":"SHP-12345","status":"IN_TRANSIT","field":"MASTER_AIRWAYBILL_NUMBER","value":"MAWB123456","origin":"Los Angeles, CA 90210","destination":"New York, NY 10001","pickUpDate":"2025-01-15","deliveryDate":"2025-01-20","trackingUrl":"https://app.mvmnt.io/shipments/550e8400-e29b-41d4-a716-446655440000"},{"query":"NOTFOUND123","id":null,"key":null,"friendlyId":null,"status":null,"field":null,"value":null,"origin":null,"destination":null,"pickUpDate":null,"deliveryDate":null,"trackingUrl":null}]
querystringrequired

Original search query (always present, even when no match found)

Example: "MAWB123456"
idstring or null(uuid)

Shipment UUID (null if not found)

Example: "550e8400-e29b-41d4-a716-446655440000"
keystring or null<= 512 characters

Client-defined key (null if not found or not set)

Example: "SHIP-001"
friendlyIdstring or null

Human-readable shipment ID (null if not found)

Example: "SHP-12345"
statusShipmentStatus (string) or null

Current shipment status (null if not found)

Example: "IN_TRANSIT"
One of:

Current status of the shipment.

Lifecycle stages:

  • DRAFT: Shipment is being created, not yet ready for processing
  • TENDER_PENDING: Awaiting carrier tender acceptance
  • TENDER_REJECTED: Carrier rejected the tender
  • ON_HOLD: Shipment is temporarily paused
  • PLANNING: Shipment is being planned/scheduled
  • SELECTED: Carrier has been selected
  • BOOKED: Carrier has confirmed the booking
  • DISPATCHED: Shipment has been dispatched to carrier

In-transit stages:

  • LOADING: Freight is being loaded at pickup
  • PICKED_UP: Freight has been picked up
  • IN_TRANSIT: Shipment is in transit
  • UNLOADING: Freight is being unloaded at delivery
  • ARRIVED_AT_DELIVERY_TERMINAL: Arrived at delivery terminal (LTL)
  • OUT_FOR_DELIVERY: Out for final delivery
  • RECOVERED: Shipment has been recovered

Final stages:

  • DELIVERED: Shipment has been delivered
  • CANCELED: Shipment has been canceled
  • CONSOLIDATED: Merged into a consolidated shipment
string(ShipmentStatus)
Enum"DRAFT""TENDER_PENDING""ON_HOLD""PLANNING""SELECTED""BOOKED""DISPATCHED""LOADING""PICKED_UP""IN_TRANSIT"
fieldShipmentReferenceField (string) or null

Reference field type that matched the query (null if not found)

One of:

Reference field types for shipment tracking.

Common field types:

  • BOL_NUMBER: Bill of Lading Number
  • PRO_NUMBER: PRO Number (carrier tracking number)
  • PURCHASE_ORDER_NUMBER: Purchase Order Number
  • CUSTOMER_REFERENCE_NUMBER: Customer Reference Number
  • CONTAINER_NUMBER: Container Number
  • MASTER_BILL_OF_LADING_NUMBER: Master Bill of Lading Number
  • HOUSE_BILL_OF_LADING_NUMBER: House Bill of Lading Number
  • MASTER_AIRWAYBILL_NUMBER: Master Airway Bill Number
  • HOUSE_AIRWAYBILL_NUMBER: House Airway Bill Number

Additional field types:

  • PICKUP_NUMBER: Pickup Number
  • DELIVERY_NUMBER: Delivery Number
  • GENERAL_LEDGER_CODE: GL Code
  • ITEM_IDENTIFICATION: Item ID
  • PART_NUMBER: Part Number
  • ACCOUNT_NUMBER: Account Number
  • CONSIGNEE_ACCOUNT_NUMBER: Consignee Account Number
  • PICKUP_LOCATION_IDENTIFICATION: Pickup Location ID
  • DELIVER_LOCATION_IDENTIFICATION: Delivery Location ID
  • PRODUCT_IDENTIFICATION: Product ID
  • OTHER_IDENTIFICATION: Other ID
  • MACROPOINT_REFERENCE_NUMBER: MacroPoint Reference Number
  • DROP_TRAILER_NUMBER: Drop Trailer Number
  • APPOINTMENT_NUMBER: Appointment Number
  • LOCATION_IDENTIFICATION: Location ID
  • TENDER_METHOD: Tender Method
  • ROUTE_NUMBER: Route Number
  • SHOW_DECORATOR_NAME: Show Decorator Name
  • SHOW_BOOTH_NUMBER: Show Booth Number
  • CARE_OF: Care Of
  • TENDER_ID: EDI Tender ID
  • ORDER_NUMBER: Order Number
  • SHOW_NAME: Show Name
  • AES_ITN: AES ITN (Automated Export System Internal Transaction Number)
  • FIRMS_CODE: FIRMS Code (Facility Information and Resources Management System)
  • IT_NUMBER: IT Number (Immediate Transportation)
  • JOB_NUMBER: Job Number
  • TMS_ID: TMS ID
  • AMS_HOUSE_BILL_OF_LADING_NUMBER: AMS House Bill of Lading Number
  • QUOTE_NUMBER: Quote Number
  • BOOKING_NUMBER: Booking Number
  • PAPS_NUMBER: PAPS Number
  • PARS_NUMBER: PARS Number
  • INTERNAL_ID: Internal ID
  • LOT_NUMBER: Lot Number
string(ShipmentReferenceField)
Enum"BOL_NUMBER""PICKUP_NUMBER""DELIVERY_NUMBER""PURCHASE_ORDER_NUMBER""GENERAL_LEDGER_CODE""CUSTOMER_REFERENCE_NUMBER""PRO_NUMBER""ITEM_IDENTIFICATION""PART_NUMBER""ACCOUNT_NUMBER"
valuestring or null

The actual value stored in the matched reference field (null if not found)

Example: "MAWB123456"
originstring or null

Origin city, state/region, and zip code (null if not found). Format: "City, ST" or "City, ST ZIP" if zip code is available.

Example: "Los Angeles, CA 90210"
destinationstring or null

Destination city, state/region, and zip code (null if not found). Format: "City, ST" or "City, ST ZIP" if zip code is available.

Example: "New York, NY 10001"
pickUpDatestring or null(date)

Scheduled or actual pickup date in ISO 8601 date format (YYYY-MM-DD). Null if not found or not set.

Example: "2025-01-15"
deliveryDatestring or null(date)

Scheduled or actual delivery date in ISO 8601 date format (YYYY-MM-DD). Null if not found or not set.

Example: "2025-01-20"
trackingUrlstring or null(uri)

Direct URL to view shipment details in MVMNT (null if not found). Uses the organization's configured domain or defaults to app.mvmnt.io.

Example: "https://app.mvmnt.io/shipments/550e8400-e29b-41d4-a716-446655440000"
truckerToolsUrlstring or null(uri)

Direct link to the Trucker Tools tracking page for the shipment's load, when live tracking is active. The MVMNT trackingUrl embeds the same map plus shipment milestones; use this one only if you want the raw Trucker Tools view.

Response
application/json
{
  "results": [
    { … },
    { … }
  ]
}

Search shipments

Request

Search shipments using OpenSearch-powered full-text and field-specific search.

This endpoint provides fast, indexed search across shipment data with support for:

  • Full-text search across multiple fields (references, locations, parties)
  • Field-specific filtering with various operators
  • Sorting and pagination
  • Saved search preferences

Note: Only active (non-deleted) shipments are searchable. Soft-deleted records are automatically excluded from all search results.

Response Formats:

  • flat (default): Returns indexed fields only for faster performance
  • full: Returns complete shipment objects with all relationships
Security
BearerAuth
Bodyapplication/jsonrequired
criteriaobject(ShipmentSearchCriteria)

Search criteria to filter shipments

paginationobject(SearchPaginationInput)

Pagination options for search requests

sortArray of objects(SearchSortOption)<= 3 items

Sort options for the search results

Example: [{"field":"createdAt","order":"desc"}]
savedSearchobject(SavedSearchLookup)

Optional saved search to load preferences from

formatstring

Response format:

  • flat: Returns only indexed fields (default, faster)
  • full: Returns complete shipment objects
Default "flat"
Enum"flat""full"
curl -i -X POST \
  https://api.mvmnt.io/v1/shipments/search \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "criteria": {
      "shipperName": {
        "operator": "INCLUDES",
        "values": [
          "Acme"
        ]
      }
    },
    "pagination": {
      "pageNumber": 1,
      "pageSize": 50
    }
  }'

Responses

Successful search results

Bodyapplication/json
dataArray of objectsrequired

Search results - either flat rows or full shipment objects based on format parameter

objectstringrequired

Object type identifier

Value"SHIPMENT_SEARCH_ROW"
Discriminator
idstring(uuid)required
friendlyIdstringrequired
Example: "SHP-0001"
statusstringrequired
orderStatusstring or null
modestring or null
tonuboolean or null
pickUpArray of strings or null

Origin city and state values for all pickup stops

pickUpCityArray of strings or null
pickUpStateArray of strings or null
pickUpZipCodeArray of strings or null
pickUpCountryArray of strings or null
dropOffArray of strings or null

Destination city and state values for all drop-off stops

dropOffCityArray of strings or null
dropOffStateArray of strings or null
dropOffZipCodeArray of strings or null
dropOffCountryArray of strings or null
pickUpStartDatetimestring or null(date-time)
dropOffStartDatetimestring or null(date-time)
bookedAtstring or null(date-time)
shipperIdstring(uuid)required
shipperNamestringrequired
carrierIdsArray of strings(uuid)
carrierNamesArray of strings
primaryRepIdstring or null(uuid)
primaryRepNamestring or null
groupIdstring or null(uuid)
groupNamestring or null
equipmentTypeArray of strings
weightnumber or null
totalMilesnumber
stopsCountinteger
revenuenumber
costnumber
profitnumber or null
profitMarginnumber or null
referenceValuesArray of strings
createdAtstring(date-time)required
orderCreatedAtstring(date-time)
paginationobject(SearchPaginationInfo)required

Pagination information for search results

pageNumberintegerrequired

Current page number

Example: 1
pageSizeintegerrequired

Number of results returned on this page

Example: 50
totalPagesintegerrequired

Total number of pages available

Example: 25
totalResultsinteger>= 0required

Total number of matching results

Response
application/json
{
  "data": [
    { … }
  ],
  "pagination": {
    "pageNumber": 1,
    "pageSize": 50,
    "totalPages": 25
  },
  "totalResults": 0
}

Filter shipments

Request

Search for shipments using filter criteria.

Each row in the response carries the fully nested shipment payload (orders with stops, freight, references, charges; loads with carriers). With a large pageSize, responses can be sizable — use a smaller page size if you only need scalar fields.

Common Filters

  • Active shipments: { "filter": { "status": { "notIn": ["DELIVERED", "CANCELED"] } } }
  • Delivered today: { "filter": { "deliveredAt": { "greaterThanOrEqualTo": "2025-01-15T00:00:00Z" } } }
  • By customer: { "filter": { "customerId": { "equalTo": "uuid" } } }
Security
BearerAuth
Bodyapplication/jsonrequired
filterobject(ShipmentFilter)
pageSizeinteger[ 1 .. 100 ]
Default 50
cursorstring
curl -i -X POST \
  https://api.mvmnt.io/v1/shipments/filter \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "filter": {
      "status": {
        "notIn": [
          "DELIVERED",
          "CANCELED"
        ]
      }
    },
    "pageSize": 50
  }'

Responses

Shipments matching filter criteria

Bodyapplication/json
dataArray of objects(Shipment)required
idstring(uuid)required
Example: "550e8400-e29b-41d4-a716-446655440000"
friendlyIdstringrequired

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

Example: "SHP-12345"
keystring or null

Client-defined reference identifier for this shipment

Example: "my-shipment-001"
statusstring(ShipmentLifecycleStatus)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"
customerobject(CustomerReference)

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.

customerRepobject(UserReference)

Customer representative

ordersArray of objects(Order)

Orders in this shipment

loadsArray of objects(LoadSummary)

Loads for carrier execution

servicesArray of objects(ServiceSummary)

Vended services

totalRevenuenumber or null

Sum of all order charges

totalCostnumber or null

Sum of all load and service costs

marginnumber or null

Revenue minus cost

marginPercentnumber or null

Margin as percentage of revenue

createdAtstring(date-time)required
updatedAtstring or null(date-time)
deliveredAtstring or null(date-time)
paginationobject(PaginationInfo)required
pageSizeintegerrequired

Number of items per page

Example: 50
hasNextPagebooleanrequired

Whether there are more pages

Example: true
hasPreviousPageboolean

Whether there are previous pages

Example: false
endCursorstring or null

Cursor for the next page (null if no next page)

Example: "eyJpZCI6IjU1MGU4NDAwLWUyOWItNDFkNC1hNzE2LTQ0NjY1NTQ0MDAwMCJ9"
Response
application/json
{
  "data": [
    { … }
  ],
  "pagination": {
    "pageSize": 50,
    "hasNextPage": true,
    "hasPreviousPage": false,
    "endCursor": "eyJpZCI6IjU1MGU4NDAwLWUyOWItNDFkNC1hNzE2LTQ0NjY1NTQ0MDAwMCJ9"
  }
}

Create a shipment

Request

Create a new shipment with orders, loads, and services.

Required fields

  • customer: Reference to the customer
  • orders: At least one order with stops and mode

What gets created

  • Shipment record
  • Order(s) with stops, freight, and charges
  • Optionally: Load(s) and Service(s)

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.

Security
BearerAuth
Bodyapplication/jsonrequired
customerobject(ResourceReferenceInput)required
One of:

Customer reference

idstring(uuid)required

Resource UUID

keystring

Client-defined reference ID

customerRepobject(ResourceReferenceInput)
One of:

Assigned customer rep

ordersArray of objects(OrderInput)non-emptyrequired

Orders to create (at least one required)

modestring(TransportMode)required

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
  • 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""AIR""OCEAN""RAIL""INTERMODAL""DRAYAGE"
stopsArray of objects(OrderStopInput)>= 2 itemsrequired

At least origin and destination stops

typestringrequired

Type of stop

Enum"PICKUP""DELIVERY"
locationobject(ResourceReferenceInput)
One of:

Reference to an existing location

addressobject(AddressInput)

Address for ad-hoc stop (if no location reference)

requestedStartDatestring(date)

Requested start date for the stop

requestedEndDatestring(date)

Requested end date for the stop

requestedStartTimestring^([01]\d|2[0-3]):([0-5]\d)$

Requested start time (HH:MM format)

requestedEndTimestring^([01]\d|2[0-3]):([0-5]\d)$

Requested end time (HH:MM format)

appointmentRequiredboolean

Whether an appointment is required

Default false
notesstring<= 2000 characters

Special instructions for the stop

freightobject(OrderFreightInput)

Freight details for an order

equipmentArray of objects(ResourceReferenceInput)

Equipment types required

referencesArray of objects

Reference numbers for the order

specialRequirementsArray of objects(ResourceReferenceInput)

Special requirements (e.g., liftgate, team drivers)

loadsArray of objects(LoadInput)

Optional loads to create

servicesArray of objects(ServiceInput)

Optional services to create

curl -i -X POST \
  https://api.mvmnt.io/v1/shipments \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "customer": {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    },
    "orders": [
      {
        "mode": "FTL",
        "stops": [
          {
            "type": "PICKUP",
            "location": {
              "id": "660e8400-e29b-41d4-a716-446655440001"
            },
            "requestedStartDate": "2025-01-20"
          },
          {
            "type": "DELIVERY",
            "location": {
              "id": "770e8400-e29b-41d4-a716-446655440002"
            },
            "requestedStartDate": "2025-01-25"
          }
        ],
        "freight": {
          "handlingUnitQuantity": 10,
          "handlingUnitType": "PALLET",
          "weight": 15000
        }
      }
    ]
  }'

Responses

Shipment created successfully

Bodyapplication/json
idstring(uuid)required
Example: "550e8400-e29b-41d4-a716-446655440000"
friendlyIdstringrequired

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

Example: "SHP-12345"
keystring or null

Client-defined reference identifier for this shipment

Example: "my-shipment-001"
statusstring(ShipmentLifecycleStatus)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"
customerobject(CustomerReference)

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.

customerRepobject(UserReference)

Customer representative

ordersArray of objects(Order)

Orders in this shipment

loadsArray of objects(LoadSummary)

Loads for carrier execution

servicesArray of objects(ServiceSummary)

Vended services

totalRevenuenumber or null

Sum of all order charges

totalCostnumber or null

Sum of all load and service costs

marginnumber or null

Revenue minus cost

marginPercentnumber or null

Margin as percentage of revenue

createdAtstring(date-time)required
updatedAtstring or null(date-time)
deliveredAtstring or null(date-time)
Response
application/json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "friendlyId": "SHP-12345",
  "key": "my-shipment-001",
  "status": "DRAFT",
  "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",
    "deletedAt": null
  },
  "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",
    "deletedAt": null
  },
  "orders": [
    { … }
  ],
  "loads": [
    { … }
  ],
  "services": [
    { … }
  ],
  "totalRevenue": 0,
  "totalCost": 0,
  "margin": 0,
  "marginPercent": 0,
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z",
  "deliveredAt": "2019-08-24T14:15:22Z"
}

Get a shipment

Request

Retrieve a shipment by ID or key.

The response includes embedded orders, loads, and services. The internal ShipmentDetail layer is hidden - all data is flattened.

Security
BearerAuth
Path
idstringrequired

Resource ID (UUID) or client key

Example: 550e8400-e29b-41d4-a716-446655440000
Query
bystring

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"
Example: by=key
curl -i -X GET \
  'https://api.mvmnt.io/v1/shipments/550e8400-e29b-41d4-a716-446655440000?by=key' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Shipment retrieved successfully

Bodyapplication/json
idstring(uuid)required
Example: "550e8400-e29b-41d4-a716-446655440000"
friendlyIdstringrequired

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

Example: "SHP-12345"
keystring or null

Client-defined reference identifier for this shipment

Example: "my-shipment-001"
statusstring(ShipmentLifecycleStatus)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"
customerobject(CustomerReference)

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.

customerRepobject(UserReference)

Customer representative

ordersArray of objects(Order)

Orders in this shipment

loadsArray of objects(LoadSummary)

Loads for carrier execution

servicesArray of objects(ServiceSummary)

Vended services

totalRevenuenumber or null

Sum of all order charges

totalCostnumber or null

Sum of all load and service costs

marginnumber or null

Revenue minus cost

marginPercentnumber or null

Margin as percentage of revenue

createdAtstring(date-time)required
updatedAtstring or null(date-time)
deliveredAtstring or null(date-time)
Response
application/json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "friendlyId": "SHP-12345",
  "key": "my-shipment-001",
  "status": "DRAFT",
  "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",
    "deletedAt": null
  },
  "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",
    "deletedAt": null
  },
  "orders": [
    { … }
  ],
  "loads": [
    { … }
  ],
  "services": [
    { … }
  ],
  "totalRevenue": 0,
  "totalCost": 0,
  "margin": 0,
  "marginPercent": 0,
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z",
  "deliveredAt": "2019-08-24T14:15:22Z"
}

Update a shipment

Request

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}
Security
BearerAuth
Path
idstringrequired

Resource ID (UUID) or client key

Example: 550e8400-e29b-41d4-a716-446655440000
Query
bystring

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"
Example: by=key
Bodyapplication/jsonrequired
customerobject(ResourceReferenceInput)
One of:

Reference to another resource by either ID or client key (used in create/update requests)

customerRepobject(ResourceReferenceInput)
One of:

Reference to another resource by either ID or client key (used in create/update requests)

curl -i -X PATCH \
  'https://api.mvmnt.io/v1/shipments/550e8400-e29b-41d4-a716-446655440000?by=key' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "customerRep": {
      "id": "550e8400-e29b-41d4-a716-446655440001"
    }
  }'

Responses

Shipment updated successfully

Bodyapplication/json
idstring(uuid)required
Example: "550e8400-e29b-41d4-a716-446655440000"
friendlyIdstringrequired

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

Example: "SHP-12345"
keystring or null

Client-defined reference identifier for this shipment

Example: "my-shipment-001"
statusstring(ShipmentLifecycleStatus)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"
customerobject(CustomerReference)

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.

customerRepobject(UserReference)

Customer representative

ordersArray of objects(Order)

Orders in this shipment

loadsArray of objects(LoadSummary)

Loads for carrier execution

servicesArray of objects(ServiceSummary)

Vended services

totalRevenuenumber or null

Sum of all order charges

totalCostnumber or null

Sum of all load and service costs

marginnumber or null

Revenue minus cost

marginPercentnumber or null

Margin as percentage of revenue

createdAtstring(date-time)required
updatedAtstring or null(date-time)
deliveredAtstring or null(date-time)
Response
application/json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "friendlyId": "SHP-12345",
  "key": "my-shipment-001",
  "status": "DRAFT",
  "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",
    "deletedAt": null
  },
  "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",
    "deletedAt": null
  },
  "orders": [
    { … }
  ],
  "loads": [
    { … }
  ],
  "services": [
    { … }
  ],
  "totalRevenue": 0,
  "totalCost": 0,
  "margin": 0,
  "marginPercent": 0,
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z",
  "deliveredAt": "2019-08-24T14:15:22Z"
}

Delete a shipment

Request

Soft delete a shipment.

The shipment and all associated orders, loads, and services are marked as deleted.

Security
BearerAuth
Path
idstringrequired

Resource ID (UUID) or client key

Example: 550e8400-e29b-41d4-a716-446655440000
Query
bystring

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"
Example: by=key
curl -i -X DELETE \
  'https://api.mvmnt.io/v1/shipments/550e8400-e29b-41d4-a716-446655440000?by=key' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Shipment deleted successfully

Response
No content

Cancel a shipment

Request

Cancel a shipment.

What happens

  • Shipment status is set to CANCELED
  • All orders are canceled
  • All loads are canceled
  • All services are canceled

Prerequisites

  • Shipment must not already be delivered or canceled
Security
BearerAuth
Path
idstringrequired

Resource ID (UUID) or client key

Example: 550e8400-e29b-41d4-a716-446655440000
Query
bystring

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"
Example: by=key
Bodyapplication/json
reasonstring<= 1000 characters

Reason for cancellation

curl -i -X POST \
  'https://api.mvmnt.io/v1/shipments/550e8400-e29b-41d4-a716-446655440000/cancel?by=key' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "reason": "Customer requested cancellation due to production delay"
  }'

Responses

Shipment canceled successfully

Bodyapplication/json
idstring(uuid)required
Example: "550e8400-e29b-41d4-a716-446655440000"
friendlyIdstringrequired

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

Example: "SHP-12345"
keystring or null

Client-defined reference identifier for this shipment

Example: "my-shipment-001"
statusstring(ShipmentLifecycleStatus)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"
customerobject(CustomerReference)

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.

customerRepobject(UserReference)

Customer representative

ordersArray of objects(Order)

Orders in this shipment

loadsArray of objects(LoadSummary)

Loads for carrier execution

servicesArray of objects(ServiceSummary)

Vended services

totalRevenuenumber or null

Sum of all order charges

totalCostnumber or null

Sum of all load and service costs

marginnumber or null

Revenue minus cost

marginPercentnumber or null

Margin as percentage of revenue

createdAtstring(date-time)required
updatedAtstring or null(date-time)
deliveredAtstring or null(date-time)
Response
application/json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "friendlyId": "SHP-12345",
  "key": "my-shipment-001",
  "status": "DRAFT",
  "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",
    "deletedAt": null
  },
  "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",
    "deletedAt": null
  },
  "orders": [
    { … }
  ],
  "loads": [
    { … }
  ],
  "services": [
    { … }
  ],
  "totalRevenue": 0,
  "totalCost": 0,
  "margin": 0,
  "marginPercent": 0,
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z",
  "deliveredAt": "2019-08-24T14:15:22Z"
}

Un-cancel a shipment

Request

Reactivate a canceled shipment.

What happens

  • Shipment status is restored to previous state
  • Orders, loads, and services are reactivated

Prerequisites

  • Shipment must be in CANCELED status
Security
BearerAuth
Path
idstringrequired

Resource ID (UUID) or client key

Example: 550e8400-e29b-41d4-a716-446655440000
Query
bystring

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"
Example: by=key
curl -i -X POST \
  'https://api.mvmnt.io/v1/shipments/550e8400-e29b-41d4-a716-446655440000/uncancel?by=key' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Shipment un-canceled successfully

Bodyapplication/json
idstring(uuid)required
Example: "550e8400-e29b-41d4-a716-446655440000"
friendlyIdstringrequired

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

Example: "SHP-12345"
keystring or null

Client-defined reference identifier for this shipment

Example: "my-shipment-001"
statusstring(ShipmentLifecycleStatus)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"
customerobject(CustomerReference)

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.

customerRepobject(UserReference)

Customer representative

ordersArray of objects(Order)

Orders in this shipment

loadsArray of objects(LoadSummary)

Loads for carrier execution

servicesArray of objects(ServiceSummary)

Vended services

totalRevenuenumber or null

Sum of all order charges

totalCostnumber or null

Sum of all load and service costs

marginnumber or null

Revenue minus cost

marginPercentnumber or null

Margin as percentage of revenue

createdAtstring(date-time)required
updatedAtstring or null(date-time)
deliveredAtstring or null(date-time)
Response
application/json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "friendlyId": "SHP-12345",
  "key": "my-shipment-001",
  "status": "DRAFT",
  "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",
    "deletedAt": null
  },
  "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",
    "deletedAt": null
  },
  "orders": [
    { … }
  ],
  "loads": [
    { … }
  ],
  "services": [
    { … }
  ],
  "totalRevenue": 0,
  "totalCost": 0,
  "margin": 0,
  "marginPercent": 0,
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z",
  "deliveredAt": "2019-08-24T14:15:22Z"
}

Duplicate a shipment

Request

Create a copy of an existing shipment.

What gets duplicated

  • Customer and customer rep
  • Order(s) with stops, freight, and references
  • Equipment and special requirements

What is NOT duplicated

  • Loads and carriers
  • Services
  • Documents
  • Status history

New shipment

The duplicate is created in DRAFT status with new dates if provided.

Security
BearerAuth
Path
idstringrequired

Resource ID (UUID) or client key

Example: 550e8400-e29b-41d4-a716-446655440000
Query
bystring

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"
Example: by=key
Bodyapplication/json
pickUpDatestring(date)

New pickup date for the duplicate

deliveryDatestring(date)

New delivery date for the duplicate

curl -i -X POST \
  'https://api.mvmnt.io/v1/shipments/550e8400-e29b-41d4-a716-446655440000/duplicate?by=key' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "pickUpDate": "2025-02-01",
    "deliveryDate": "2025-02-05"
  }'

Responses

Shipment duplicated successfully

Bodyapplication/json
originalShipmentIdstring(uuid)required
newShipmentIdstring(uuid)required
newShipmentKeystringrequired
Response
application/json
{
  "originalShipmentId": "550e8400-e29b-41d4-a716-446655440000",
  "newShipmentId": "660e8400-e29b-41d4-a716-446655440001",
  "newShipmentKey": "SHP-12346"
}

Mark shipment ready to invoice

Request

Mark a shipment as ready for invoicing.

What happens

  • Shipment billing status changes to READY_TO_INVOICE
  • Shipment is now visible in invoice generation workflows

Prerequisites

  • Shipment must have delivery documents attached
  • Shipment must be in DOCS_NEEDED or NOT_READY_TO_INVOICE status
Security
BearerAuth
Path
idstringrequired

Resource ID (UUID) or client key

Example: 550e8400-e29b-41d4-a716-446655440000
Query
bystring

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"
Example: by=key
curl -i -X POST \
  'https://api.mvmnt.io/v1/shipments/550e8400-e29b-41d4-a716-446655440000/ready-to-invoice?by=key' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Shipment marked ready to invoice

Bodyapplication/json
idstring(uuid)required
Example: "550e8400-e29b-41d4-a716-446655440000"
friendlyIdstringrequired

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

Example: "SHP-12345"
keystring or null

Client-defined reference identifier for this shipment

Example: "my-shipment-001"
statusstring(ShipmentLifecycleStatus)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"
customerobject(CustomerReference)

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.

customerRepobject(UserReference)

Customer representative

ordersArray of objects(Order)

Orders in this shipment

loadsArray of objects(LoadSummary)

Loads for carrier execution

servicesArray of objects(ServiceSummary)

Vended services

totalRevenuenumber or null

Sum of all order charges

totalCostnumber or null

Sum of all load and service costs

marginnumber or null

Revenue minus cost

marginPercentnumber or null

Margin as percentage of revenue

createdAtstring(date-time)required
updatedAtstring or null(date-time)
deliveredAtstring or null(date-time)
Response
application/json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "friendlyId": "SHP-12345",
  "key": "my-shipment-001",
  "status": "DRAFT",
  "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",
    "deletedAt": null
  },
  "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",
    "deletedAt": null
  },
  "orders": [
    { … }
  ],
  "loads": [
    { … }
  ],
  "services": [
    { … }
  ],
  "totalRevenue": 0,
  "totalCost": 0,
  "margin": 0,
  "marginPercent": 0,
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z",
  "deliveredAt": "2019-08-24T14:15:22Z"
}

Revert shipment to not ready

Request

Revert a shipment from ready-to-invoice back to not ready.

What happens

  • Shipment billing status changes back to NOT_READY_TO_INVOICE

Prerequisites

  • Shipment must be in READY_TO_INVOICE status
  • Shipment must not already be invoiced
Security
BearerAuth
Path
idstringrequired

Resource ID (UUID) or client key

Example: 550e8400-e29b-41d4-a716-446655440000
Query
bystring

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"
Example: by=key
curl -i -X POST \
  'https://api.mvmnt.io/v1/shipments/550e8400-e29b-41d4-a716-446655440000/not-ready-to-invoice?by=key' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Shipment reverted to not ready

Bodyapplication/json
idstring(uuid)required
Example: "550e8400-e29b-41d4-a716-446655440000"
friendlyIdstringrequired

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

Example: "SHP-12345"
keystring or null

Client-defined reference identifier for this shipment

Example: "my-shipment-001"
statusstring(ShipmentLifecycleStatus)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"
customerobject(CustomerReference)

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.

customerRepobject(UserReference)

Customer representative

ordersArray of objects(Order)

Orders in this shipment

loadsArray of objects(LoadSummary)

Loads for carrier execution

servicesArray of objects(ServiceSummary)

Vended services

totalRevenuenumber or null

Sum of all order charges

totalCostnumber or null

Sum of all load and service costs

marginnumber or null

Revenue minus cost

marginPercentnumber or null

Margin as percentage of revenue

createdAtstring(date-time)required
updatedAtstring or null(date-time)
deliveredAtstring or null(date-time)
Response
application/json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "friendlyId": "SHP-12345",
  "key": "my-shipment-001",
  "status": "DRAFT",
  "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",
    "deletedAt": null
  },
  "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",
    "deletedAt": null
  },
  "orders": [
    { … }
  ],
  "loads": [
    { … }
  ],
  "services": [
    { … }
  ],
  "totalRevenue": 0,
  "totalCost": 0,
  "margin": 0,
  "marginPercent": 0,
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z",
  "deliveredAt": "2019-08-24T14:15:22Z"
}

Generate invoice for shipment

Request

Generate an invoice PDF for the shipment.

What happens

  • Invoice PDF is generated
  • Invoice document is attached to the shipment
  • Shipment billing status changes to INVOICED

Prerequisites

  • Shipment must be in READY_TO_INVOICE status
Security
BearerAuth
Path
idstringrequired

Resource ID (UUID) or client key

Example: 550e8400-e29b-41d4-a716-446655440000
Query
bystring

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"
Example: by=key
curl -i -X POST \
  'https://api.mvmnt.io/v1/shipments/550e8400-e29b-41d4-a716-446655440000/invoice/generate?by=key' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Invoice generated

Bodyapplication/json
shipmentIdstring(uuid)
invoiceIdstring(uuid)

The generated invoice ID

documentIdstring(uuid)

The invoice PDF document ID

downloadUrlstring(uri)

URL to download the invoice PDF

Response
application/json
{
  "shipmentId": "47efd5a2-af91-4417-950a-7f546cd1b5cf",
  "invoiceId": "4f163819-178d-470c-a246-d6768476a6ec",
  "documentId": "4704590c-004e-410d-adf7-acb7ca0a7052",
  "downloadUrl": "http://example.com"
}

Teams

Team management operations

Operations

Users

User management operations

Operations

Vendors

Vendor management operations

Operations

Vendor Contacts

Vendor contact management operations

Operations

Vendor Payment Methods

Vendor payment method management operations

Operations

Event Notifications

Webhooks