---
title: "book a shipment"
method: POST
path: "/freights/booking"
tags: ["Freight"]
---

# book a shipment

`POST /freights/booking`

## Request

- Base URL: `https://stg.wearewarp.com/api/v1`
- URL: `https://stg.wearewarp.com/api/v1/freights/booking`
- Auth: API key in header `apikey`

**Request parameters**
| Name               | Type                                | Required/Optional | Description                                                                                                                                                                                                                          |
|--------------------|-------------------------------------|-------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| quoteId            | String                              | Required unless WARP has enabled booking without a quote for your account | The `quote_id` returned by a previous call to POST /freights/quote. The quote must not be expired and must not have been used by an earlier booking. The booking must match the quote **exactly**: pickup/delivery zipcodes, every item's height, length, width, sizeUnit, totalWeight, weightUnit and quantity, and the pickup/delivery/additional service lists - otherwise the request is rejected with 400 `invalid_field_data` (e.g. `Pickup Zipcode 90001 does not match with quoting request 90058.`). For PARCEL quotes send the items in `IN` and `lbs` on both the quote and the booking. |
| shipmentType       | String ("LTL", "FTL" or "PARCEL")   | Optional          | Default is "LTL". Ignored when `quoteId` is provided: the shipment type of the quote is used.                                                                                                                                       |
| pickupInfo         | Object <**StopInfo**>               | Required          | The details of the pick up stop.                                                                                                                                                                                                     |
| deliveryInfo       | Object <**StopInfo**>               | Required          | The details of the delivery stop.                                                                                                                                                                                                    |
| listItems          | Array<**Item**>                     | Required          | The list of commodities being shipped. Same **Item** schema as POST /freights/quote; `height` must be <= 108 and `temperature_limit` is accepted here (stored on the shipment).                                                    |
| pickupServices     | Array<**PickupService**>            | Optional          | Any pickup services required to service the shipment in the pickup location.                                                                                                                                                         |
| deliveryServices   | Array<**DeliveryService**>          | Optional          | Any delivery services required to service the shipment in the delivery location.                                                                                                                                                     |
| additionalServices | Array<**AdditionalService**>        | Optional          | Any additional services required to service the shipment.                                                                                                                                                                            |
| dedicatedLane      | String                              | Optional          | Only relevant for accounts that WARP has configured for dedicated-lane booking (the value is the lane code provided by WARP). Dedicated lanes are set up by WARP for the account - please contact the Warp team.                                                                                                                                                                                 |
| vehicleType        | VehicleType                         | Optional          | The vehicle. If not provided, the system will automatically select the best vehicle based on the items.                                                                                                                              |
| refNum             | String                              | Optional          | An optional external reference assigned by the customer when creating the shipment. This identifier helps link the shipment in this platform with records maintained in other systems such as order management, warehouse, transportation, or accounting systems. |
| insuranceQuoteId   | String                              | Optional          | The insuranceQuoteId returned in the insurance block of POST /freights/quote. Provide it to purchase insurance for this shipment.                                                                                                    |

<br /> 
**StopInfo** schema:
| Name                 | Type                | Required/Optional | Description                                                                                                       |
|----------------------|---------------------|-------------------|-------------------------------------------------------------------------------------------------------------------|
| locationName         | String              | Optional          | Location Name/Shipper Name/Consignee Name.                                                                        |
| contactName          | String              | Optional          | The pickup contact name.                                                                                          |
| contactPhone         | String              | Required          | The pickup contact phone.                                                                                         |
| phoneExtension       | String              | Optional          | The contact phone extension.                                                                                      |
| contactEmail         | String              | Optional          | The pickup contact email.                                                                                         |
| address              | Object<**Address**> | Required          | Pickup Address information                                                                                        |
| requiresAppointment  | Boolean             | Optional          | **true** if this stop requires appointment,                                                                       |
| appointmentInfo      | Object              | Optional          | The range of times for which this stop is scheduled. Provide it when requiresAppointment is true.                 |
| appointmentInfo.from | String              | Optional          | The start time of the appointment window (ISO 8601 format).                                                       |
| appointmentInfo.to   | String              | Optional          | The end time of the appointment window (ISO 8601 format).                                                         |
| windowTime           | Object              | Required for pickupInfo, optional for deliveryInfo | The window time. `from` must not be later than `to`.                                         |
| windowTime.from      | String              | Required when windowTime is provided | Timestamp at which stop window starts (ISO 8601 format).                                               |
| windowTime.to        | String              | Required when windowTime is provided | Timestamp at which stop window ends (ISO 8601 format).                                                 |
| instructions         | String              | Optional          | Instructions to follow at stop                                                                                    |
| refNum               | String              | Optional          | Shipper-defined reference codes to facilitate the stop.                                                           |

<br /> 
**Address** schema:
| Name    | Type   | Required/Optional | Description            |
|---------|--------|-------------------|------------------------|
| street2 | String | Optional          | Line 2 of the address. |
| street  | String | Required          | Line 1 of the address. |
| city    | String | Required          | City of the address.   |
| state   | String | Required          | State of the address.  |
| zipcode | String | Required          | Postal code.           |

<br /> 
**Response parameters**
| Name             | Type   | Description                                                                                                                                                  |
|------------------|--------|--------------------------------------------------------------------------------------------------------------------------------------------------------------|
| message          | String | "Success" when the booking is fully completed, otherwise the payment required message (see **Payment required** below).                                       |
| trackingNumber   | String | Identifier to track the shipment with POST /freights/tracking. Currently this is the shipment code (e.g. `S-00524-2635`), i.e. the same value as shipmentNumber. |
| orderNumber      | String | The display number (code) of the order, e.g. `P-01723-2449`.                                                                                                |
| orderId          | String | The ID of the created order.                                                                                                                                  |
| shipmentId       | String | The ID of the created shipment.                                                                                                                               |
| shipmentNumber   | String | The display number (code) of the shipment, e.g. `S-00524-2635`.                                                                                             |
| refNum           | String | The unique reference numbers of the pickup and delivery stops, comma separated (e.g. `PO-001, DO-001`).                                                     |
| insuranceStatus  | String | Only present when insuranceQuoteId was provided. "booked" if the insurance was booked successfully, "failed" if it could not be booked.                        |
| paymentLink      | String | Only present when the customer balance is not enough to cover this booking. Open this link to add funds and complete the payment.                              |
| payment          | Object | Only present when the booking was paid with the saved card (see **Pay by saved card** below): `{ method: "card", amount_charged, card_fee, last4 }`.          |

<br /> 
**Payment required** <br />

If the customer balance is not enough to cover this booking, the order is still created but it is put on hold: the shipment is not processed until the payment is completed. In that case the response returns **paymentLink** together with the message *"Your booking has been created successfully. Please add funds to your balance to complete payment and continue with the shipment."*

Always check for **paymentLink** in the response - when it is present, open the link to add funds and complete the payment.

<br /> 
**Pay by saved card** <br />

If an admin of your organization turned on *Pay by card for API bookings* in the customer portal (Settings > API Access), a booking that the balance cannot cover is charged to the selected saved card instead: the amount charged is the booking total plus the card processing fee, and the response includes **payment**. If the card cannot be charged, no order is created and the API returns:

| HTTP | code                     | Meaning                                                                 |
|------|--------------------------|-------------------------------------------------------------------------|
| 402  | CHARGE_FAILED            | The card was declined. Update the card in the customer portal and retry. |
| 402  | PAYMENT_ACTION_REQUIRED  | The card requires authentication (3D Secure) and cannot be charged automatically. |
| 409  | BOOKING_IN_PROGRESS      | Another booking request for the same quote is still being processed.  |
| 400  | CARD_INSURANCE_NOT_SUPPORTED | insuranceQuoteId cannot be used on a booking paid by saved card.   |

## Request body

- BookingShipment
  - `quoteId` string: The quote_id returned by POST /freights/quote. Required unless WARP has enabled booking without a quote for your account. Must not be expired or already booked; the booking payload must match the quote exactly.
  - `pickupInfo` StopInfo, required
    - `locationName` string
    - `contactName` string
    - `contactPhone` string, required
    - `phoneExtension` string
    - `contactEmail` string
    - `address` Address, required
      - `street2` string
      - `street` string, required
      - `city` string, required
      - `state` string, required
      - `zipcode` string, required
    - `requiresAppointment` boolean
    - `appointmentInfo` object: Appointment window of the stop (ISO 8601). Provide it when requiresAppointment is true.
      - `from` string
      - `to` string
    - `windowTime` object: Time window of the stop (ISO 8601). Required for pickupInfo, optional for deliveryInfo. `from` must not be later than `to`.
      - `from` string, date-time, required
      - `to` string, date-time, required
    - `instructions` string
    - `refNum` string
  - `deliveryInfo` StopInfo, required
    - `locationName` string
    - `contactName` string
    - `contactPhone` string, required
    - `phoneExtension` string
    - `contactEmail` string
    - `address` Address, required
      - `street2` string
      - `street` string, required
      - `city` string, required
      - `state` string, required
      - `zipcode` string, required
    - `requiresAppointment` boolean
    - `appointmentInfo` object: Appointment window of the stop (ISO 8601). Provide it when requiresAppointment is true.
      - `from` string
      - `to` string
    - `windowTime` object: Time window of the stop (ISO 8601). Required for pickupInfo, optional for deliveryInfo. `from` must not be later than `to`.
      - `from` string, date-time, required
      - `to` string, date-time, required
    - `instructions` string
    - `refNum` string
  - `listItems` BookShipmentItem[], required
    - `name` string
    - `height` number, required: Maximum 108 on POST /freights/booking; maximum 85 on POST /freights/freight-quote, /freights/book and the multi-stops endpoints (checked on the raw value, whatever the sizeUnit).
    - `length` number, required
    - `width` number, required
    - `sizeUnit` 'IN' | 'FT', required
    - `totalWeight` number, required
    - `weightUnit` 'lbs' | 'kgs', required
    - `quantity` integer, required
    - `packaging` string: Packaging unit of the line item (e.g. Pallet). Defaults to Pallet.
    - `temperature_limit` object: Temperature-controlled (reefer) freight is NOT supported yet by the quote endpoints: POST /freights/quote rejects any non-zero min/max and POST /freights/freight-quote rejects the field entirely with 400 `Reefer Shipment is not supported yet!`. Omit this field unless instructed otherwise by WARP.
      - `min` number: Minimum temperature.
      - `max` number: Maximum temperature.
    - `stackable` boolean
    - `notes` string
    - `freightClass` string: NMFC freight class of the line item (e.g. 70).
    - `barcodes` string[]
  - `pickupServices` PickupService[]
    - `quantity` number, required
    - `service` 'photo-required-pickup' | 'liftgate-pickup' | 'convention-trade-show-pickup' | 'inside-pickup' | 'limited-access-pickup' | 'residential-pickup' | 'construction-site-pickup' | 'pickup-appointment' | 'pickup-layover' | 'detention-shipper' | 'drop-empty' | 'driver-assist-pickup' | 'drop-and-hook-pickup' | 'inside-pickup-upstairs-mezzanine-trash-removal' | 'inside-pickup-back-side-of-the-house' | 'inside-pickup-living-space-garage', required: Pickup service options
  - `deliveryServices` DeliveryService[]
    - `quantity` number, required
    - `service` 'photo-required-delivery' | 'liftgate-delivery' | 'convention-trade-show-delivery' | 'inside-delivery' | 'limited-access-delivery' | 'residential-delivery' | 'construction-site-delivery' | 'delivery-appointment' | 'delivery-layover' | 'lumper' | 'detention-receiver' | 'redelivery' | 'drop-loaded' | 'driver-assist-delivery' | 'drop-and-hook-delivery' | 'inside-delivery-upstairs-mezzanine-trash-removal' | 'inside-delivery-back-side-of-the-house' | 'inside-delivery-living-space-garage', required: Delivery service options
  - `additionalServices` AdditionalService[]
    - `quantity` number, required
    - `service` 'photo-required' | 'sort-n-seg' | 'extra-stop' | 'extra-miles' | 'driver-assist' | 'notify' | 'check_calls' | 'otp_late_fee' | 'otd_late_fee' | 'carrier_otp' | 'carrier_otd' | 'tonu' | 'miscellaneous' | 'deduction' | 'racket_straps' | 'trailer_rental' | 'storage' | 'cross_dock_charge' | 'drop_loaded_equipment' | 'drop_and_hook' | 'drop_equipment' | 'reweigh_reclass' | 'insurance' | 'chassis_rental', required: Addtional service options
  - `insuranceQuoteId` string: Optional. The insuranceQuoteId returned by the quote endpoint. Provide it to purchase insurance for this shipment.
  - `shipmentType` 'LTL' | 'FTL' | 'PARCEL': Optional. Ignored when quoteId is provided - the shipment type of the quote is used.
  - `vehicleType` VehicleType
    - `code` 'DRY_VAN_53' | 'STRAIGHT_TRUCK_26' | 'CARGO_VAN': The type of vehicle (optional. If not provided, the system will automatically select the best vehicle type based on the shipment type and the items.)
  - `dedicatedLane` string: Optional. Only relevant for accounts that WARP has configured for dedicated-lane booking: the value is the lane code provided by WARP. Dedicated lanes are set up by WARP for the account - please contact the WARP team.
  - `refNum` string: Optional external reference assigned by the customer to the shipment.

## Response `200`

successful operation

- BookingSuccess
  - `message` string: Result message. "Success" when the booking is fully completed. When the customer balance is not enough to cover this booking, it returns a payment required message and paymentLink is also included.
  - `trackingNumber` string: Identifier to track the shipment with POST /freights/tracking. Currently the shipment code, i.e. the same value as shipmentNumber.
  - `orderNumber` string: The display number (code) of the order.
  - `orderId` string
  - `shipmentId` string
  - `shipmentNumber` string: The display number (code) of the shipment.
  - `refNum` string: Unique reference numbers of the pickup and delivery stops, comma separated.
  - `insuranceStatus` 'booked' | 'failed': Only present when insuranceQuoteId was provided. "booked" if insurance was booked insurance successfully, "failed" if it could not be booked insurance
  - `paymentLink` string, uri: Only present when the customer balance is not enough to cover this booking. The order is still created, but it is on hold until the payment is completed. Open this link to add funds and complete the payment.

## Other responses

- `400`: Bad Request - the request payload is missing fields or contains invalid data.
- `401`: Unauthorized - the apikey header is missing or does not match any active API key.
- `403`: Forbidden - the customer account is suspended. The body carries `message` only, without `code`.
- `429`: Too Many Requests - the quoting rate limit of the API key was exceeded (only POST /freights/quote, /freights/freight-quote and /freights/quote/multi-stops are rate limited; limits apply per UTC hour and per UTC day). The `Retry-After` header holds the number of seconds until the window resets.
- `500`: Internal Server Error - an unknown error has occurred.

---

[API](https://skmtc.dev/wearewarp/apis/warp-api-documentation.md) · [All operations](https://skmtc.dev/wearewarp/apis/warp-api-documentation/llms.txt) · [OpenAPI document](https://skmtc.dev/wearewarp/apis/warp-api-documentation/revisions/01526741bb48?raw)