# Shipments

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


## Get tracking link

 - [POST /shipments/track](https://docs.mvmnt.io/apis/openapi/shipments/trackshipments.md): 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)

## Filter shipments

 - [POST /shipments/filter](https://docs.mvmnt.io/apis/openapi/shipments/filtershipments.md): 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" } } }

## Create a shipment

 - [POST /shipments](https://docs.mvmnt.io/apis/openapi/shipments/createshipment.md): 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.

## Get a shipment

 - [GET /shipments/{id}](https://docs.mvmnt.io/apis/openapi/shipments/getshipment.md): 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.

## Update a shipment

 - [PATCH /shipments/{id}](https://docs.mvmnt.io/apis/openapi/shipments/updateshipment.md): 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}

## Delete a shipment

 - [DELETE /shipments/{id}](https://docs.mvmnt.io/apis/openapi/shipments/deleteshipment.md): Soft delete a shipment.

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

## Cancel a shipment

 - [POST /shipments/{id}/cancel](https://docs.mvmnt.io/apis/openapi/shipments/cancelshipment.md): 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

## Un-cancel a shipment

 - [POST /shipments/{id}/uncancel](https://docs.mvmnt.io/apis/openapi/shipments/uncancelshipment.md): 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

## Duplicate a shipment

 - [POST /shipments/{id}/duplicate](https://docs.mvmnt.io/apis/openapi/shipments/duplicateshipment.md): 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.

## Mark shipment ready to invoice

 - [POST /shipments/{id}/ready-to-invoice](https://docs.mvmnt.io/apis/openapi/shipments/markshipmentreadytoinvoice.md): 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

## Revert shipment to not ready

 - [POST /shipments/{id}/not-ready-to-invoice](https://docs.mvmnt.io/apis/openapi/shipments/markshipmentnotreadytoinvoice.md): 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

## Generate invoice for shipment

 - [POST /shipments/{id}/invoice/generate](https://docs.mvmnt.io/apis/openapi/shipments/generateshipmentinvoice.md): 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