Freight

book a shipment

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.

**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. | **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. | **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 }`. | **Payment required**

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.

**Pay by saved card**

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

quoteIdstring

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.

insuranceQuoteIdstring

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.

dedicatedLanestring

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.

refNumstring

Optional external reference assigned by the customer to the shipment.

Example request

{
  "quoteId": "W01KH5PB2V9QJ6Z8M4T3R7X1C0D",
  "pickupInfo": {
    "locationName": "Location Name/ Shipper Name / Consignee Name",
    "contactName": "Poppy",
    "contactPhone": "234566533",
    "phoneExtension": "123",
    "contactEmail": "test@testmail.com",
    "address": {
      "street": "1220 Satterwhite Rd",
      "city": "Buda",
      "state": "TX",
      "zipcode": "12345"
    },
    "requiresAppointment": true,
    "appointmentInfo": {
      "from": "2023-01-04T16:04:40.000Z",
      "to": "2023-01-04T16:06:42.000Z"
    },
    "windowTime": {
      "from": "2023-01-13T15:03:07.000Z",
      "to": "2023-01-13T15:07:07.000Z"
    },
    "instructions": "Driver needs to pull up to the back door and ring the bell 4 times.",
    "refNum": "reference number"
  },
  "deliveryInfo": {
    "locationName": "Location Name/ Shipper Name / Consignee Name",
    "contactName": "Poppy",
    "contactPhone": "234566533",
    "phoneExtension": "123",
    "contactEmail": "test@testmail.com",
    "address": {
      "street": "1220 Satterwhite Rd",
      "city": "Buda",
      "state": "TX",
      "zipcode": "12345"
    },
    "requiresAppointment": true,
    "appointmentInfo": {
      "from": "2023-01-04T16:04:40.000Z",
      "to": "2023-01-04T16:06:42.000Z"
    },
    "windowTime": {
      "from": "2023-01-13T15:03:07.000Z",
      "to": "2023-01-13T15:07:07.000Z"
    },
    "instructions": "Driver needs to pull up to the back door and ring the bell 4 times.",
    "refNum": "reference number"
  },
  "listItems": [
    {
      "name": "Item Name",
      "height": 48,
      "length": 48,
      "width": 40,
      "sizeUnit": "IN",
      "totalWeight": 500,
      "weightUnit": "lbs",
      "quantity": 1,
      "packaging": "Pallet",
      "stackable": false,
      "notes": "Notes here"
    }
  ],
  "pickupServices": [
    {
      "quantity": 1,
      "service": "photo-required-pickup"
    }
  ],
  "deliveryServices": [
    {
      "quantity": 1,
      "service": "photo-required-delivery"
    }
  ],
  "additionalServices": [
    {
      "quantity": 1,
      "service": "photo-required"
    }
  ],
  "insuranceQuoteId": "01J8ZQ7X8N2R6V5F3C4B9D0E1F",
  "vehicleType": {
    "code": "CARGO_VAN"
  },
  "refNum": "PO-123456"
}

Response

successful operation

messagestring

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.

trackingNumberstring

Identifier to track the shipment with POST /freights/tracking. Currently the shipment code, i.e. the same value as shipmentNumber.

orderNumberstring

The display number (code) of the order.

orderIdstring

shipmentIdstring

shipmentNumberstring

The display number (code) of the shipment.

refNumstring

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

paymentLinkstring 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.

Example response

{
  "message": "Success",
  "trackingNumber": "S-00524-2635",
  "orderNumber": "P-01723-2449",
  "orderId": "01H3W439G5J5Y282KQFQTAQGTD",
  "shipmentId": "01H4YJBE0NP5NGEN3W07Z6YPM4",
  "shipmentNumber": "S-00524-2635",
  "refNum": "PO-123456, DO-123456",
  "insuranceStatus": "booked",
  "paymentLink": "https://customer.wearewarp.com/dashboard/pay-orders"
}

book a shipment

Request

Request body

Example request

Response

Example response

Changes