MVMNT Shipments API
Shipment tracking and management operations. Shipments contain orders, loads, and services.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/mvmnt-shipments-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
OpenAPI Specification
openapi: 3.2.0
info:
title: MVMNT Shipments API
version: 1.0.0
description: "The MVMNT API enables you to automate freight brokerage workflows by integrating\ndirectly with our Transportation Management System.\n\n## Authentication\n\nOAuth 2.0 client credentials flow. See [Authentication Guide](/getting-started/authentication)\nfor details.\n\n### Token Endpoint\n\n```\nPOST https://api.mvmnt.io/oauth2/token\n```\n\n#### Request\n\n**Headers:**\n```http\nContent-Type: application/x-www-form-urlencoded\n```\n\n**Body Parameters:**\n```\ngrant_type=client_credentials\nclient_id=YOUR_CLIENT_ID\nclient_secret=YOUR_CLIENT_SECRET\n```\n\n#### Example Request\n\n```bash\ncurl -X POST https://api.mvmnt.io/oauth2/token \\\n -H \"Content-Type: application/x-www-form-urlencoded\" \\\n -d \"grant_type=client_credentials\" \\\n -d \"client_id=YOUR_CLIENT_ID\" \\\n -d \"client_secret=YOUR_CLIENT_SECRET\"\n```\n\n#### Success Response\n\n**Status:** `200 OK`\n\n```json\n{\n \"access_token\": \"eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...\",\n \"token_type\": \"Bearer\",\n \"expires_in\": 3600\n}\n```\n\n**Response Fields:**\n- `access_token`: JWT Bearer token to use for API requests\n- `token_type`: Always `Bearer`\n- `expires_in`: Token lifetime in seconds (3600 = 1 hour)\n"
contact:
name: MVMNT Support
email: support@mvmnt.io
url: https://docs.mvmnt.io
license:
name: Proprietary
url: https://mvmnt.io/legal/terms
x-parsed-md-description:
result:
- $$mdtype: Node
errors: []
lines:
- 0
- 2
inline: false
attributes: {}
children:
- $$mdtype: Node
errors: []
lines:
- 0
- 2
inline: false
attributes: {}
children:
- $$mdtype: Node
errors: []
lines:
- 0
- 2
inline: true
attributes:
content: The MVMNT API enables you to automate freight brokerage workflows by integrating
children: []
type: text
annotations: []
slots: {}
- $$mdtype: Node
errors: []
lines:
- 0
- 2
inline: true
attributes: {}
children: []
type: softbreak
annotations: []
slots: {}
- $$mdtype: Node
errors: []
lines:
- 0
- 2
inline: true
attributes:
content: directly with our Transportation Management System.
children: []
type: text
annotations: []
slots: {}
type: inline
annotations: []
slots: {}
type: paragraph
annotations: []
slots: {}
- $$mdtype: Node
errors: []
lines:
- 3
- 4
inline: false
attributes:
level: 2
children:
- $$mdtype: Node
errors: []
lines:
- 3
- 4
inline: false
attributes: {}
children:
- $$mdtype: Node
errors: []
lines:
- 3
- 4
inline: true
attributes:
content: Authentication
children: []
type: text
annotations: []
slots: {}
type: inline
annotations: []
slots: {}
type: heading
annotations: []
slots: {}
- $$mdtype: Node
errors: []
lines:
- 5
- 6
inline: false
attributes: {}
children:
- $$mdtype: Node
errors: []
lines:
- 5
- 6
inline: false
attributes: {}
children:
- $$mdtype: Node
errors: []
lines:
- 5
- 6
inline: true
attributes:
content: 'OAuth 2.0 client credentials flow. See '
children: []
type: text
annotations: []
slots: {}
- $$mdtype: Node
errors: []
lines:
- 5
- 6
inline: true
attributes:
href: /getting-started/authentication
children:
- $$mdtype: Node
errors: []
lines:
- 5
- 6
inline: true
attributes:
content: Authentication Guide
children: []
type: text
annotations: []
slots: {}
type: link
annotations: []
slots: {}
redocly:::linkOriginal:href: /getting-started/authentication
- $$mdtype: Node
errors: []
lines:
- 5
- 6
inline: true
attributes:
content: ' for details.'
children: []
type: text
annotations: []
slots: {}
type: inline
annotations: []
slots: {}
type: paragraph
annotations: []
slots: {}
servers:
- url: https://api.mvmnt.io/v1
description: Production
security:
- BearerAuth: []
tags:
- name: Shipments
description: 'Shipment tracking and management operations.
Shipments contain orders, loads, and services.
'
paths:
/shipments/track:
post:
summary: Get tracking link
description: '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)
'
operationId: trackShipments
tags:
- Shipments
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ShipmentTrackRequest'
examples:
singleSearch:
summary: Single shipment lookup
description: Look up a single shipment by reference value
value:
searches:
- query: MAWB123456
multipleSearches:
summary: Multiple shipments with field filter
description: Look up multiple shipments, limiting search to specific reference field types
value:
searches:
- query: MAWB123456
- query: BOL789
- query: PRO-001
referenceFields:
- MASTER_AIRWAYBILL_NUMBER
- BOL_NUMBER
- PRO_NUMBER
bulkLookup:
summary: Bulk BOL lookup
description: Look up multiple shipments by BOL number only
value:
searches:
- query: BOL-2025-001
- query: BOL-2025-002
- query: BOL-2025-003
- query: BOL-2025-004
referenceFields:
- BOL_NUMBER
responses:
'200':
description: Track results returned successfully
content:
application/json:
schema:
$ref: '#/components/schemas/ShipmentTrackResponse'
examples:
allFound:
summary: All shipments found
description: All search queries returned matching shipments
value:
results:
- 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: BOL789012
id: 660e8400-e29b-41d4-a716-446655440001
key: SHIP-002
friendlyId: SHP-12346
status: DELIVERED
field: BOL_NUMBER
value: BOL-789012
origin: Chicago, IL 60601
destination: Miami, FL 33101
pickUpDate: '2025-01-16'
deliveryDate: '2025-01-21'
trackingUrl: https://app.mvmnt.io/shipments/660e8400-e29b-41d4-a716-446655440001
mixedResults:
summary: Some found, some not found
description: Mix of found and not-found results
value:
results:
- query: MAWB123456
id: 550e8400-e29b-41d4-a716-446655440000
key: SHIP-001
friendlyId: SHP-12345
status: PICKED_UP
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
noneFound:
summary: No shipments found
description: No matching shipments for any query
value:
results:
- query: UNKNOWN-REF-1
id: null
key: null
friendlyId: null
status: null
field: null
value: null
origin: null
destination: null
pickUpDate: null
deliveryDate: null
trackingUrl: null
- query: UNKNOWN-REF-2
id: null
key: null
friendlyId: null
status: null
field: null
value: null
origin: null
destination: null
pickUpDate: null
deliveryDate: null
trackingUrl: null
'400':
$ref: '#/components/responses/BadRequestError'
'401':
$ref: '#/components/responses/UnauthorizedError'
'422':
$ref: '#/components/responses/ValidationError'
'429':
$ref: '#/components/responses/RateLimitExceeded'
/shipments/filter:
post:
summary: Filter shipments
description: '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" } } }`
'
operationId: filterShipments
tags:
- Shipments
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ShipmentFilterRequest'
examples:
activeShipments:
summary: Filter active shipments
value:
filter:
status:
notIn:
- DELIVERED
- CANCELED
pageSize: 50
inTransit:
summary: Filter in-transit shipments
value:
filter:
status:
equalTo: IN_TRANSIT
responses:
'200':
description: Shipments matching filter criteria
content:
application/json:
schema:
type: object
required:
- data
- pagination
properties:
data:
type: array
items:
$ref: '#/components/schemas/Shipment'
pagination:
$ref: '#/components/schemas/PaginationInfo'
'400':
$ref: '#/components/responses/BadRequestError'
'401':
$ref: '#/components/responses/UnauthorizedError'
'422':
$ref: '#/components/responses/ValidationError'
/shipments:
post:
summary: Create a shipment
description: '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.
'
operationId: createShipment
tags:
- Shipments
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ShipmentInput'
examples:
basicShipment:
summary: Basic TL shipment
value:
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:
'201':
description: Shipment created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Shipment'
'400':
$ref: '#/components/responses/BadRequestError'
'401':
$ref: '#/components/responses/UnauthorizedError'
'422':
$ref: '#/components/responses/ValidationError'
/shipments/{id}:
get:
summary: Get a shipment
description: '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.
'
operationId: getShipment
tags:
- Shipments
parameters:
- $ref: '#/components/parameters/IdOrClientKey'
- $ref: '#/components/parameters/LookupBy'
responses:
'200':
description: Shipment retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Shipment'
'401':
$ref: '#/components/responses/UnauthorizedError'
'404':
$ref: '#/components/responses/NotFoundError'
patch:
summary: Update a shipment
description: '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}
'
operationId: updateShipment
tags:
- Shipments
parameters:
- $ref: '#/components/parameters/IdOrClientKey'
- $ref: '#/components/parameters/LookupBy'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ShipmentPatch'
examples:
changeCustomerRep:
summary: Change customer rep
value:
customerRep:
id: 550e8400-e29b-41d4-a716-446655440001
responses:
'200':
description: Shipment updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Shipment'
'400':
$ref: '#/components/responses/BadRequestError'
'401':
$ref: '#/components/responses/UnauthorizedError'
'404':
$ref: '#/components/responses/NotFoundError'
'422':
$ref: '#/components/responses/ValidationError'
delete:
summary: Delete a shipment
description: 'Soft delete a shipment.
The shipment and all associated orders, loads, and services are marked as deleted.
'
operationId: deleteShipment
tags:
- Shipments
parameters:
- $ref: '#/components/parameters/IdOrClientKey'
- $ref: '#/components/parameters/LookupBy'
responses:
'204':
description: Shipment deleted successfully
'401':
$ref: '#/components/responses/UnauthorizedError'
'404':
$ref: '#/components/responses/NotFoundError'
/shipments/{id}/cancel:
post:
summary: Cancel a shipment
description: '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
'
operationId: cancelShipment
tags:
- Shipments
parameters:
- $ref: '#/components/parameters/IdOrClientKey'
- $ref: '#/components/parameters/LookupBy'
requestBody:
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/CancelShipmentRequest'
examples:
withReason:
summary: Cancel with reason
value:
reason: Customer requested cancellation due to production delay
responses:
'200':
description: Shipment canceled successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Shipment'
'400':
$ref: '#/components/responses/BadRequestError'
'401':
$ref: '#/components/responses/UnauthorizedError'
'404':
$ref: '#/components/responses/NotFoundError'
'409':
description: Cannot cancel - shipment is delivered or already canceled
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Error'
/shipments/{id}/uncancel:
post:
summary: Un-cancel a shipment
description: '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
'
operationId: uncancelShipment
tags:
- Shipments
parameters:
- $ref: '#/components/parameters/IdOrClientKey'
- $ref: '#/components/parameters/LookupBy'
responses:
'200':
description: Shipment un-canceled successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Shipment'
'400':
$ref: '#/components/responses/BadRequestError'
'401':
$ref: '#/components/responses/UnauthorizedError'
'404':
$ref: '#/components/responses/NotFoundError'
'409':
description: Cannot un-cancel - shipment is not canceled
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Error'
/shipments/{id}/duplicate:
post:
summary: Duplicate a shipment
description: '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.
'
operationId: duplicateShipment
tags:
- Shipments
parameters:
- $ref: '#/components/parameters/IdOrClientKey'
- $ref: '#/components/parameters/LookupBy'
requestBody:
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/DuplicateShipmentRequest'
examples:
withNewDates:
summary: Duplicate with new dates
value:
pickUpDate: '2025-02-01'
deliveryDate: '2025-02-05'
responses:
'201':
description: Shipment duplicated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/DuplicateShipmentResponse'
example:
originalShipmentId: 550e8400-e29b-41d4-a716-446655440000
newShipmentId: 660e8400-e29b-41d4-a716-446655440001
newShipmentKey: SHP-12346
'400':
$ref: '#/components/responses/BadRequestError'
'401':
$ref: '#/components/responses/UnauthorizedError'
'404':
$ref: '#/components/responses/NotFoundError'
/shipments/{id}/ready-to-invoice:
post:
summary: Mark shipment ready to invoice
description: '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
'
operationId: markShipmentReadyToInvoice
tags:
- Shipments
parameters:
- $ref: '#/components/parameters/IdOrClientKey'
- $ref: '#/components/parameters/LookupBy'
responses:
'200':
description: Shipment marked ready to invoice
content:
application/json:
schema:
$ref: '#/components/schemas/Shipment'
'400':
$ref: '#/components/responses/BadRequestError'
'401':
$ref: '#/components/responses/UnauthorizedError'
'404':
$ref: '#/components/responses/NotFoundError'
'409':
description: Shipment not in valid status for this action
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Error'
/shipments/{id}/not-ready-to-invoice:
post:
summary: Revert shipment to not ready
description: '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
'
operationId: markShipmentNotReadyToInvoice
tags:
- Shipments
parameters:
- $ref: '#/components/parameters/IdOrClientKey'
- $ref: '#/components/parameters/LookupBy'
responses:
'200':
description: Shipment reverted to not ready
content:
application/json:
schema:
$ref: '#/components/schemas/Shipment'
'400':
$ref: '#/components/responses/BadRequestError'
'401':
$ref: '#/components/responses/UnauthorizedError'
'404':
$ref: '#/components/responses/NotFoundError'
'409':
description: Shipment not in valid status for this action
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Error'
/shipments/{id}/invoice/generate:
post:
summary: Generate invoice for shipment
description: '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
'
operationId: generateShipmentInvoice
tags:
- Shipments
parameters:
- $ref: '#/components/parameters/IdOrClientKey'
- $ref: '#/components/parameters/LookupBy'
responses:
'200':
description: Invoice generated
content:
application/json:
schema:
type: object
properties:
shipmentId:
type: string
format: uuid
invoiceId:
type: string
format: uuid
description: The generated invoice ID
documentId:
type: string
format: uuid
description: The invoice PDF document ID
downloadUrl:
type: string
format: uri
description: URL to download the invoice PDF
'400':
$ref: '#/components/responses/BadRequestError'
'401':
$ref: '#/components/responses/UnauthorizedError'
'404':
$ref: '#/components/responses/NotFoundError'
'409':
description: Shipment not in valid status for invoice generation
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Error'
components:
responses:
NotFoundError:
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: not_found
message: Resource not found
ValidationError:
description: Validation error - invalid field values
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
example:
error: validation_error
message: Invalid field values
details:
- field: email
message: Must be a valid email address
- field: status
message: Must be one of PENDING, ACTIVE, INACTIVE
RateLimitExceeded:
description: Rate limit exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: rate_limit_exceeded
message: Too many requests. Please retry after 60 seconds.
headers:
X-RateLimit-Limit:
description: Request limit per minute
schema:
type: integer
X-RateLimit-Remaining:
description: Remaining requests in current window
schema:
type: integer
X-RateLimit-Reset:
description: Unix timestamp when rate limit resets
schema:
type: integer
Retry-After:
description: Seconds to wait before retrying
schema:
type: integer
BadRequestError:
description: Bad request - invalid input
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: bad_request
message: Invalid request parameters
UnauthorizedError:
description: Unauthorized - invalid or missing access token
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: unauthorized
message: Invalid or expired access token
schemas:
OrderCharge:
type: object
properties:
id:
type: string
format: uuid
chargeCode:
$ref: '#/components/schemas/ResourceReference'
description:
type:
- string
- 'null'
amount:
type: number
quantity:
type: number
default: 1
rate:
type:
- number
- 'null'
ShipmentFilter:
type: object
properties:
id:
$ref: '#/components/schemas/UUIDFilter'
key:
$ref: '#/components/schemas/StringFilter'
status:
$ref: '#/components/schemas/ShipmentStatusFilter'
customerId:
$ref: '#/components/schemas/UUIDFilter'
customerRepId:
$ref: '#/components/schemas/UUIDFilter'
createdAt:
$ref: '#/components/schemas/DatetimeFilter'
updatedAt:
$ref: '#/components/schemas/DatetimeFilter'
deliveredAt:
$ref: '#/components/schemas/DatetimeFilter'
and:
type: array
items:
$ref: '#/components/schemas/ShipmentFilter'
or:
type: array
items:
$ref: '#/components/schemas/ShipmentFilter'
not:
$ref: '#/components/schemas/ShipmentFilter'
OrderFreight:
type: object
properties:
handlingUnitQuantity:
type:
- integer
- 'null'
handlingUnitType:
type:
- string
- 'null'
weight:
type:
- number
- 'null'
description: Weight in pounds
volume:
type:
- number
- 'null'
description: Volume in cubic feet
length:
type:
- number
- 'null'
width:
type:
- number
- 'null'
height:
type:
- number
- 'null'
commodityDescription:
type:
- string
- 'null'
hazmat:
type: boolean
stackable:
type: boolean
DuplicateShipmentRequest:
type: object
properties:
pickUpDate:
type: string
format: date
description: New pickup date for the duplicate
deliveryDate:
type: string
format: date
description: New delivery date for the duplicate
description: Request body for duplicating a shipment
OrderStop:
type: object
# --- truncated at 32 KB (81 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/mvmnt/refs/heads/main/openapi/mvmnt-shipments-api-openapi.yml