Freight

[Experimental] Book a shipment using a previous quote ID

Provide all the details required for delivery, linked with id of selected quote option (quoteId = options[].id of POST /freights/freight-quote). The quote option must not be expired and must not have been booked already.<br/><br/>The booking must match the quote exactly: pickup/delivery zipcodes, every item's height, length, width, sizeUnit, totalWeight, weightUnit and quantity, and the service lists - otherwise the request is rejected with 400 invalid_field_data and a message such as Pickup Zipcode 90001 does not match with quoting request 90058., Drop-off zipcode ... does not match with quoting request ..., Number of items 2 does not match with number of items in quoting request 1., List of items do not match with list of Items in quoting request. or additionalServices does not match with quoting request. (also pickupInfo.serviceOptions / deliveryInfo.serviceOptions).<br/><br/>PARCEL quotes: send the items in IN and lbs on both the quote and the booking. The quote stores parcel items converted to inches/pounds and the booking compares the raw values, so any other unit is reported as a mismatch.<br/><br/>Validation notes: pickupInfo.contactPhone and deliveryInfo.contactPhone are required. timeWindow.from / timeWindow.to (and appointmentInfo) must be ISO 8601 date-times in the future and from must not be later than to. items[].height must be <= 85.<br/><br/>If the customer balance is not enough to cover this booking, the order is still created but it is put on hold until the payment is completed. In that case the response also includes message and paymentLink - open that link to add funds and complete the payment.<br/><br/>If Pay by card for API bookings is turned on in the customer portal (Settings > API Access), that booking is charged to the selected saved card instead (total + card processing fee) and the response includes payment { method, amount_charged, card_fee, last4 }. A card that cannot be charged returns HTTP 402 with code CHARGE_FAILED or PAYMENT_ACTION_REQUIRED and no order is created; HTTP 409 BOOKING_IN_PROGRESS means another request for the same quote is in progress. Insurance (insuranceQuoteId) is not available on a booking paid by saved card (HTTP 400 CARD_INSURANCE_NOT_SUPPORTED).

post/freights/book

Request

  • Base URL: https://stg.wearewarp.com/api/v1
  • URL: https://stg.wearewarp.com/api/v1/freights/book
  • Auth: API key in header apikey

Request body

quoteIdstring required

The options[].id of the chosen option from POST /freights/freight-quote. Must not be expired or already booked; the booking payload must match the quote exactly.

additionalServicesstring[]
insuranceQuoteIdstring

Optional. The insuranceQuoteId returned in the insurance block of the quote endpoint. Provide it to purchase insurance for this shipment.

Example request

{
  "quoteId": "01HG9W6CMAWHNWTVXDKW9QYFS9",
  "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-13T15:03:07.000Z",
      "to": "2023-01-13T15:07:07.000Z"
    },
    "timeWindow": {
      "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."
  },
  "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-13T15:03:07.000Z",
      "to": "2023-01-13T15:07:07.000Z"
    },
    "timeWindow": {
      "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."
  },
  "items": [
    {
      "name": "Item Name",
      "height": 48,
      "length": 48,
      "width": 40,
      "sizeUnit": "IN",
      "totalWeight": 500,
      "weightUnit": "lbs",
      "quantity": 1,
      "packaging": "Pallet",
      "stackable": false,
      "notes": "Notes here"
    }
  ],
  "insuranceQuoteId": "01J8ZQ7X8N2R6V5F3C4B9D0E1F"
}

Response

successful creation

messagestring

Only present when the customer balance is not enough to cover this booking. In that case paymentLink is also included.

trackingNumberstring

Tracking number of the created shipment - accepted by POST /freights/tracking.

proNumberstring

The display number (code) of the created order.

orderIdstring
shipmentIdsstring[]

Display numbers (codes) of the created shipments - not ULIDs. Use them as shipmentNumber / shipmentId on the other endpoints (both accept the code).

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": "Your booking has been created successfully. Please add funds to your balance to complete payment and continue with the shipment.",
  "trackingNumber": "2E2EWQATEF8K",
  "proNumber": "P-01723-2449",
  "orderId": "01H3W439G5J5Y282KQFQTAQGTD",
  "shipmentIds": [
    "S-00524-2635"
  ],
  "insuranceStatus": "booked",
  "paymentLink": "https://customer.wearewarp.com/dashboard/pay-orders"
}

Changes

No recorded changes to this operation across all 1 revision of this API.