Skip to content
API Reference/
/
Cancel a shipment

MVMNT API (1.0.0)

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

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)
Download OpenAPI description
openapi.json
openapi.yaml
Overview
URL
https://docs.mvmnt.io
MVMNT Support
support@mvmnt.io
License
Proprietary
Languages
Servers
Mock server
https://docs.mvmnt.io/_mock/apis/openapi
Production
https://api.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

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"}]
searches[].​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://docs.mvmnt.io/_mock/apis/openapi/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}]
results[].​querystringrequired

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

Example: "MAWB123456"
results[].​idstring or null(uuid)

Shipment UUID (null if not found)

Example: "550e8400-e29b-41d4-a716-446655440000"
results[].​keystring or null<= 512 characters

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

Example: "SHIP-001"
results[].​friendlyIdstring or null

Human-readable shipment ID (null if not found)

Example: "SHP-12345"
results[].​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

Final stages:

  • DELIVERED: Shipment has been delivered
  • CANCELED: Shipment has been canceled
string(ShipmentStatus)
Enum"DRAFT""TENDER_PENDING""ON_HOLD""PLANNING""SELECTED""BOOKED""DISPATCHED""LOADING""PICKED_UP""IN_TRANSIT"
results[].​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
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"
results[].​valuestring or null

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

Example: "MAWB123456"
results[].​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"
results[].​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"
results[].​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"
results[].​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"
results[].​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"
Response
application/json
{
  "results": [
    { … },
    { … }
  ]
}

Filter shipments

Request

Search for shipments using filter criteria.

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://docs.mvmnt.io/_mock/apis/openapi/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
data[].​idstring(uuid)required
Example: "550e8400-e29b-41d4-a716-446655440000"
data[].​keystringrequired

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

Example: "SHP-12345"
data[].​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

Final:

  • DELIVERED: Delivered
  • CANCELED: Canceled
Enum"DRAFT""TENDER_PENDING""ON_HOLD""PLANNING""SELECTED""BOOKED""DISPATCHED""LOADING""PICKED_UP""IN_TRANSIT"
data[].​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.

data[].​customerRepobject(UserReference)

Customer representative

data[].​ordersArray of objects(Order)

Orders in this shipment

data[].​loadsArray of objects(LoadSummary)

Loads for carrier execution

data[].​servicesArray of objects(ServiceSummary)

Vended services

data[].​totalRevenuenumber or null

Sum of all order charges

data[].​totalCostnumber or null

Sum of all load and service costs

data[].​marginnumber or null

Revenue minus cost

data[].​marginPercentnumber or null

Margin as percentage of revenue

data[].​createdAtstring(date-time)required
data[].​updatedAtstring or null(date-time)
data[].​deliveredAtstring or null(date-time)
paginationobject(PaginationInfo)required
pagination.​pageSizeintegerrequired

Number of items per page

Example: 50
pagination.​hasNextPagebooleanrequired

Whether there are more pages

Example: true
pagination.​hasPreviousPageboolean

Whether there are previous pages

Example: false
pagination.​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

customer.​idstring(uuid)required

Resource UUID

customer.​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)

orders[].​modestring(TransportMode)required

Transportation mode.

  • TL: Full Truckload
  • LTL: Less than Truckload
  • AIR: Air freight
  • OCEAN: Ocean freight
  • RAIL: Rail freight
  • INTERMODAL: Intermodal (multiple modes)
  • DRAYAGE: Drayage/cartage
Enum"TL""LTL""AIR""OCEAN""RAIL""INTERMODAL""DRAYAGE"
orders[].​stopsArray of objects(OrderStopInput)>= 2 itemsrequired

At least origin and destination stops

orders[].​stops[].​typestringrequired

Type of stop

Enum"PICKUP""DELIVERY""CROSS_DOCK"
orders[].​stops[].​locationobject(ResourceReferenceInput)
One of:

Reference to an existing location

orders[].​stops[].​addressobject(AddressInput)

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

orders[].​stops[].​requestedStartDatestring(date)

Requested start date for the stop

orders[].​stops[].​requestedEndDatestring(date)

Requested end date for the stop

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

Requested start time (HH:MM format)

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

Requested end time (HH:MM format)

orders[].​stops[].​appointmentRequiredboolean

Whether an appointment is required

Default false
orders[].​stops[].​notesstring<= 2000 characters

Special instructions for the stop

orders[].​freightobject(OrderFreightInput)

Freight details for an order

orders[].​equipmentArray of objects(ResourceReferenceInput)

Equipment types required

orders[].​referencesArray of objects

Reference numbers for the order

orders[].​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://docs.mvmnt.io/_mock/apis/openapi/shipments \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "customer": {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    },
    "orders": [
      {
        "mode": "TL",
        "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"
keystringrequired

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

Example: "SHP-12345"
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

Final:

  • DELIVERED: Delivered
  • CANCELED: Canceled
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",
  "key": "SHP-12345",
  "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://docs.mvmnt.io/_mock/apis/openapi/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"
keystringrequired

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

Example: "SHP-12345"
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

Final:

  • DELIVERED: Delivered
  • CANCELED: Canceled
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",
  "key": "SHP-12345",
  "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://docs.mvmnt.io/_mock/apis/openapi/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"
keystringrequired

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

Example: "SHP-12345"
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

Final:

  • DELIVERED: Delivered
  • CANCELED: Canceled
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",
  "key": "SHP-12345",
  "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://docs.mvmnt.io/_mock/apis/openapi/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://docs.mvmnt.io/_mock/apis/openapi/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"
keystringrequired

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

Example: "SHP-12345"
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

Final:

  • DELIVERED: Delivered
  • CANCELED: Canceled
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",
  "key": "SHP-12345",
  "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://docs.mvmnt.io/_mock/apis/openapi/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"
keystringrequired

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

Example: "SHP-12345"
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

Final:

  • DELIVERED: Delivered
  • CANCELED: Canceled
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",
  "key": "SHP-12345",
  "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://docs.mvmnt.io/_mock/apis/openapi/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://docs.mvmnt.io/_mock/apis/openapi/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"
keystringrequired

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

Example: "SHP-12345"
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

Final:

  • DELIVERED: Delivered
  • CANCELED: Canceled
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",
  "key": "SHP-12345",
  "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://docs.mvmnt.io/_mock/apis/openapi/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"
keystringrequired

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

Example: "SHP-12345"
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

Final:

  • DELIVERED: Delivered
  • CANCELED: Canceled
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",
  "key": "SHP-12345",
  "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://docs.mvmnt.io/_mock/apis/openapi/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