# Loads

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


## Filter loads

 - [POST /loads/filter](https://docs.mvmnt.io/apis/openapi/loads/filterloads.md): Search for loads using filter criteria.

## Common Filters

- By shipment: { "filter": { "shipmentId": { "equalTo": "uuid" } } }
- Active loads: { "filter": { "status": { "notIn": ["DELIVERED", "CANCELED"] } } }
- TL loads: { "filter": { "mode": { "equalTo": "TL" } } }

## Create a load

 - [POST /loads](https://docs.mvmnt.io/apis/openapi/loads/createload.md): Create a new load for a shipment.

## What happens

- Load is created for the specified shipment
- Optionally assigns an initial carrier

## Note

Loads are typically created as part of shipment creation.
Use this endpoint to add additional loads to an existing shipment.

## Get a load

 - [GET /loads/{id}](https://docs.mvmnt.io/apis/openapi/loads/getload.md): Retrieve a load by ID.

The response includes embedded carriers and stops.

## Update a load

 - [PATCH /loads/{id}](https://docs.mvmnt.io/apis/openapi/loads/updateload.md): Update load fields.

Note: To manage carriers, use the carrier-specific endpoints.

## Delete a load

 - [DELETE /loads/{id}](https://docs.mvmnt.io/apis/openapi/loads/deleteload.md): Soft delete a load.

## Prerequisites

- Load must not have any active carriers

## Add carrier to load

 - [POST /loads/{id}/add-carrier](https://docs.mvmnt.io/apis/openapi/loads/addcarriertoload.md): Add an additional carrier to a load.

## Use cases

- Split loads (multiple carriers for same load)
- Adding backup carrier
- Re-assigning after TONU/bounce

## What happens

- New LoadCarrier record is created
- Carrier is notified (if configured)

## Rebook a TONU load

 - [POST /loads/{id}/rebook](https://docs.mvmnt.io/apis/openapi/loads/rebookload.md): Create a new load to replace a TONU'd load.

## Use case

After a carrier reports TONU, use this to create a replacement load
that can be assigned to a new carrier.

## What happens

- New Load is created with same stops
- Original load remains in TONU status
- New load is ready for carrier assignment

## Get load carrier

 - [GET /loads/{loadId}/carriers/{carrierId}](https://docs.mvmnt.io/apis/openapi/loads/getloadcarrier.md): Retrieve a specific carrier assignment for a load.

## Update load carrier

 - [PATCH /loads/{loadId}/carriers/{carrierId}](https://docs.mvmnt.io/apis/openapi/loads/updateloadcarrier.md): Update carrier assignment details.

Use this to update driver info, truck/trailer numbers, or contact.

## Bounce carrier

 - [POST /loads/{loadId}/carriers/{carrierId}/bounce](https://docs.mvmnt.io/apis/openapi/loads/bouncecarrier.md): Mark carrier as bounced (rejected load without payment).

## What happens

- LoadCarrier status changes to BOUNCED
- Carrier is removed from active execution
- No payment is recorded

## When to use

Use bounce when carrier rejects the load before dispatch,
or fails to show up without prior notice.

For carriers who were dispatched but cancelled, use TONU instead.

## Report TONU

 - [POST /loads/{loadId}/carriers/{carrierId}/tonu](https://docs.mvmnt.io/apis/openapi/loads/reporttonu.md): Report Truck Ordered Not Used (TONU).

## What happens

- LoadCarrier status changes to TONU
- TONU costs are recorded if provided
- Optionally creates a replacement load

## When to use

Use TONU when:
- Carrier was dispatched but load was cancelled
- Carrier arrived but freight wasn't ready
- Carrier was turned away at shipper

TONU typically involves some payment to the carrier.