# Create a load

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.

Endpoint: POST /loads
Version: 1.0.0
Security: BearerAuth

## Request fields (application/json):

  - `shipmentId` (string, required)
    Parent shipment ID

  - `load` (object, required)

  - `load.mode` (string, 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"

  - `load.orderStopIds` (array)
    Order stop IDs to include in this load

  - `load.carrier` (object)
    Initial carrier assignment

  - `load.carrier.carrier` (any, required)

  - `load.carrier.contact` (any)

  - `load.carrier.charges` (array)

  - `load.carrier.charges.chargeCode` (any, required)

  - `load.carrier.charges.description` (string)

  - `load.carrier.charges.amount` (number, required)

  - `load.carrier.charges.quantity` (number)

  - `load.carrier.driverName` (string)

  - `load.carrier.driverPhone` (string)

  - `load.carrier.truckNumber` (string)

  - `load.carrier.trailerNumber` (string)

## Response 201 fields (application/json):

  - `id` (string, required)
    Example: "550e8400-e29b-41d4-a716-446655440000"

  - `key` (string,null)
    Human-readable load ID
    Example: "LD-12345"

  - `shipmentId` (string)
    Parent shipment

  - `shipmentKey` (string,null)
    Parent shipment friendly ID

  - `mode` (string)
    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"

  - `status` (string, required)
    Current status of the load.

Pre-transit:
- SOURCING: Looking for carrier
- BOOKED: Carrier booked
- DISPATCHED: Dispatched to carrier

In-transit:
- LOADING: Loading at pickup
- PICKED_UP: Picked up
- IN_TRANSIT: In transit
- UNLOADING: Unloading at delivery

Final:
- DELIVERED: Delivered
- CANCELED: Canceled
    Enum: "SOURCING", "BOOKED", "DISPATCHED", "LOADING", "PICKED_UP", "IN_TRANSIT", "UNLOADING", "DELIVERED", "CANCELED"

  - `stops` (array)
    Load stops

  - `stops.orderStopId` (string)
    Reference to the order stop

  - `stops.sequence` (integer)

  - `stops.type` (string)
    Enum: "PICKUP", "DELIVERY", "CROSS_DOCK"

  - `stops.address` (object)
    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.

  - `stops.address.line1` (string, required)
    Primary street address line
    Example: "123 Main St"

  - `stops.address.line2` (string,null)
    Secondary address line (suite, floor, etc.)
    Example: "Suite 400"

  - `stops.address.city` (string, required)
    City name
    Example: "Chicago"

  - `stops.address.country` (string, required)
    Country name or code
    Example: "USA"

  - `stops.address.market` (string, required)
    Market or region identifier
    Example: "CHI"

  - `stops.address.latitude` (string,null)
    Latitude coordinate
    Example: "41.8781"

  - `stops.address.longitude` (string,null)
    Longitude coordinate
    Example: "-87.6298"

  - `stops.address.isAirportOrAirbase` (boolean, required)
    Whether this location is an airport or airbase

  - `stops.address.isConstructionOrUtilitySite` (boolean, required)
    Whether this location is a construction or utility site

  - `stops.address.isSmartyValidated` (boolean, required)
    Whether address has been validated by SmartyStreets
    Example: true

  - `stops.address.obeysDst` (boolean, required)
    Whether this location observes daylight saving time
    Example: true

  - `stops.address.cityId` (string,null)
    Reference to standardized city record (internal use)

  - `stops.scheduledArrival` (string,null)

  - `stops.actualArrival` (string,null)

  - `stops.actualDeparture` (string,null)

  - `carriers` (array)
    Carrier assignments (flattened from LoadCarriersConnection)

  - `carriers.carrier` (object)
    Enhanced reference to a carrier resource (returned in responses).
Includes full carrier details in addition to id/key.

Note: Does NOT include nested references (contacts, etc.) to prevent recursion.
Maximum nesting depth: 1 level.

  - `carriers.carrier.id` (string, required)
    Carrier UUID
    Example: "550e8400-e29b-41d4-a716-446655440000"

  - `carriers.carrier.key` (string,null)
    Client-defined reference ID if set
    Example: "ERP-CARRIER-SWIFT"

  - `carriers.carrier.name` (string, required)
    Carrier company name
    Example: "Swift Transportation"

  - `carriers.carrier.phoneNumber` (string,null)
    Primary phone number
    Example: "+1-555-987-6543"

  - `carriers.carrier.email` (string,null)
    Primary email address
    Example: "dispatch@swifttrans.com"

  - `carriers.carrier.createdAt` (string, required)
    When the carrier was created
    Example: "2025-01-15T10:00:00Z"

  - `carriers.carrier.updatedAt` (string, required)
    When the carrier was last updated
    Example: "2025-01-15T14:30:00Z"

  - `carriers.carrier.deletedAt` (string,null)
    When the carrier was soft deleted (null if active)

  - `carriers.contact` (object)

  - `carriers.contact.name` (string)

  - `carriers.contact.phone` (string,null)

  - `carriers.contact.email` (string,null)

  - `carriers.status` (string)
    Status of the carrier assignment.
- ACTIVE: Carrier is actively assigned
- TONU: Truck Ordered Not Used (carrier dispatched but cancelled)
- BOUNCED: Carrier bounced/rejected load
    Enum: "ACTIVE", "TONU", "BOUNCED"

  - `carriers.billingStatus` (string)
    Billing status for the load (AP side).
- AWAITING_INVOICE: Waiting for carrier invoice
- INVOICE_IN_REVIEW: Invoice received, under review
- APPROVED_TO_PAY: Approved for payment
- PAID: Paid to carrier
    Enum: "AWAITING_INVOICE", "INVOICE_IN_REVIEW", "APPROVED_TO_PAY", "PAID"

  - `carriers.bookedAt` (string,null)

  - `carriers.dispatchedAt` (string,null)

  - `carriers.charges` (array)
    Flattened charges array

  - `carriers.charges.chargeCode` (object)
    Reference to another resource (returned in responses)

  - `carriers.charges.chargeCode.id` (string, required)
    Resource UUID

  - `carriers.charges.description` (string,null)

  - `carriers.charges.amount` (number)

  - `carriers.charges.quantity` (number)

  - `carriers.totalCost` (number,null)
    Sum of all charges

  - `carriers.driverName` (string,null)

  - `carriers.driverPhone` (string,null)

  - `carriers.truckNumber` (string,null)

  - `carriers.trailerNumber` (string,null)

  - `carriers.createdAt` (string)

  - `carriers.updatedAt` (string,null)

  - `totalCost` (number,null)
    Total carrier costs

  - `pickedUpAt` (string,null)

  - `deliveredAt` (string,null)

## Response 400 fields (application/json):

  - `error` (string, required)
    Error code

  - `message` (string, required)
    Human-readable error message

## Response 401 fields (application/json):

  - `error` (string, required)
    Error code

  - `message` (string, required)
    Human-readable error message

## Response 422 fields (application/json):

  - `error` (string, required)
    Error code
    Example: "validation_error"

  - `message` (string, required)
    Human-readable error message

  - `details` (array, required)
    Validation error details

  - `details.field` (string, required)
    Field name that failed validation

  - `details.message` (string, required)
    Validation error message