MVMNT Shipments API
Shipment tracking and management operations. Shipments contain orders, loads, and services.
OpenAPI Specification
openapi: 3.1.0
info:
title: MVMNT Bill Payments 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:
schemas:
OrderStop:
type: object
properties:
id:
type: string
format: uuid
type:
type: string
enum:
- PICKUP
- DELIVERY
- CROSS_DOCK
sequence:
type: integer
description: Stop order in the route
location:
$ref: '#/components/schemas/ResourceReference'
address:
$ref: '#/components/schemas/Address'
requestedStartDate:
type:
- string
- 'null'
format: date
requestedEndDate:
type:
- string
- 'null'
format: date
requestedStartTime:
type:
- string
- 'null'
requestedEndTime:
type:
- string
- 'null'
actualArrival:
type:
- string
- 'null'
format: date-time
actualDeparture:
type:
- string
- 'null'
format: date-time
appointmentRequired:
type: boolean
notes:
type:
- string
- 'null'
LoadCarrierInput:
type: object
required:
- carrier
properties:
carrier:
$ref: '#/components/schemas/ResourceReferenceInput'
description: Carrier reference
contact:
$ref: '#/components/schemas/ResourceReferenceInput'
description: Carrier contact
charges:
type: array
items:
type: object
required:
- chargeCode
- amount
properties:
chargeCode:
$ref: '#/components/schemas/ResourceReferenceInput'
description:
type: string
amount:
type: number
quantity:
type: number
default: 1
driverName:
type: string
driverPhone:
type: string
truckNumber:
type: string
trailerNumber:
type: string
ValidationError:
type: object
required:
- error
- message
- details
properties:
error:
type: string
description: Error code
example: validation_error
message:
type: string
description: Human-readable error message
details:
type: array
description: Validation error details
items:
type: object
required:
- field
- message
properties:
field:
type: string
description: Field name that failed validation
message:
type: string
description: Validation error message
ShipmentStatusFilter:
type: object
properties:
equalTo:
$ref: '#/components/schemas/ShipmentLifecycleStatus'
notEqualTo:
$ref: '#/components/schemas/ShipmentLifecycleStatus'
in:
type: array
items:
$ref: '#/components/schemas/ShipmentLifecycleStatus'
notIn:
type: array
items:
$ref: '#/components/schemas/ShipmentLifecycleStatus'
Address:
type: object
description: 'Physical address/location details (nested, without id).
This is an embedded object representing a Location record. The id is managed
internally and not exposed in the API.
'
required:
- line1
- city
- country
- market
- isAirportOrAirbase
- isConstructionOrUtilitySite
- isSmartyValidated
- obeysDst
properties:
line1:
type: string
description: Primary street address line
example: 123 Main St
line2:
type:
- string
- 'null'
description: Secondary address line (suite, floor, etc.)
example: Suite 400
city:
type: string
description: City name
example: Chicago
country:
type: string
description: Country name or code
example: USA
market:
type: string
description: Market or region identifier
example: CHI
latitude:
type:
- string
- 'null'
description: Latitude coordinate
example: '41.8781'
longitude:
type:
- string
- 'null'
description: Longitude coordinate
example: '-87.6298'
isAirpo
# --- 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