Shipment Booking API

Creates a new shipment booking for either Small Parcel or LTL (Less Than Truckload) delivery

POST/api/shipments/book-shipmentSmall Parcel & LTL

Description

This endpoint allows you to book a shipment after obtaining rates from the rates API. The booking process differs based on the shipment type:

Small Parcel: For packages under 150 lbs, typically handled by carriers like UPS, USPS
LTL (Less Than Truckload): For larger freight shipments over 150 lbs, handled by freight carriers like SAIA, ABF, Ward, XPO, Estes

Authentication

JSON

headers: {
  "Authorization": "Bearer {YOUR_API_KEY}",
  "Content-Type": "application/json"
}

Request Parameters

Common Parameters

Parameter	Type	Required	Description
shop	string	No	Shop identifier
shipment_from	object	Yes	Origin address details
shipment_to	object	Yes	Destination address and recipient details
pickup_date	string	Yes	Pickup date in YYYY-MM-DD format
pickup_window	object	Yes	Pickup time window configuration
from_details	object	Yes	Shipper contact information
to_details	object	Yes	Consignee contact information
packages	array	Yes	Array of package details
options	array	No	Additional shipping options
order_id	string	No	External order identifier
rate_id	string	Yes	Rate ID obtained from rates API
service_code	string	Yes*	Service code (required for Small Parcel)
uuid	string	Yes	Unique identifier from rates API
rate_type	string	Yes	Type of rate: shipengine_rates or shipengine_ltl_rates
company_name	string	Yes	Carrier company name from rates API
rate_price	number	Yes	Rate price from rates API
rate_currency	string	Yes	Currency code (e.g., "USD")
estimate_days	string	Yes	Estimated delivery time
currency	string	Yes	Order currency
order_fulfilled_status	boolean	Yes	Fulfillment status flag
service_type	string	Yes	Service type description
order_reference_code	string	No	Reference code for the order

Shipment From Object

Parameter	Type	Required	Description
address_line1	string	Yes	Primary address line
address_line2	string	No	Secondary address line
city	string	Yes	City name
stateCode	string	Yes	State/province code
postalCode	string	Yes	Postal/ZIP code
countryCode	string	Yes	ISO country code

Shipment To Object

Parameter	Type	Required	Description
destination	string	Yes	Full destination address string
company	string	No	Recipient company name
name	string	Yes	Recipient name
email	string	Yes	Recipient email address
phone	string	No	Recipient phone number
address_line1	string	Yes	Primary address line
address_line2	string	No	Secondary address line
city	string	Yes	City name
state	string	Yes	State/province name
country	string	Yes	Country name
postalCode	string	Yes	Postal/ZIP code
countryCode	string	Yes	ISO country code
stateCode	string	Yes	State/province code
weight	number	Yes	Total shipment weight
weight_unit	string	Yes	Weight unit ("pound", "kg")
description	string	Yes	Shipment description

Shipper Details (from_details)

Parameter	Type	Required	Description
pickup_window.start_at	string	Yes	Pickup window start time (HH:MM:SS format)
pickup_window.end_at	string	Yes	Pickup window end time (HH:MM:SS format)
pickup_window.closing_at	string	Yes	Facility closing time (HH:MM:SS format)
company_name	string	Yes	Shipper company name
contact_name	string	Yes	Shipper contact person name
contact_no	string	Yes	Shipper contact phone number
contact_email	string	Yes	Shipper contact email address
is_residential	boolean	Yes	Whether the pickup location is residential

Consignee Details (to_details)

Parameter	Type	Required	Description
destination_window.start_at	string	Yes	Pickup window start time (HH:MM:SS format)
destination_window.end_at	string	Yes	Pickup window end time (HH:MM:SS format)
destination_window.closing_at	string	Yes	Facility closing time (HH:MM:SS format)
company_name	string	Yes	Consignee company name
contact_name	string	Yes	Consignee contact person name
contact_no	string	Yes	Consignee contact phone number
contact_email	string	Yes	Consignee contact email address
is_residential	boolean	Yes	Whether the delivery location is residential

Package Object

Parameter	Type	Required	Description
quantity	number	Yes	Number of packages
type	string	Yes	Package type ("Box", "Pallet", etc.)
class	string	Yes	Freight class (e.g., "60", "175")
nmfc	string	No	NMFC code (required for LTL)
nmfc_sub	string	No	NMFC Sub code (required for LTL)
weight	string	Yes	Package weight
weight_unit	string	Yes	Weight unit ("pound", "kg")
length	string	Yes	Package length
width	string	Yes	Package width
height	string	Yes	Package height
dimension_unit	string	Yes	Dimension unit ("inch", "cm")
description	string	Yes	Package description
pieces	number	Yes	Number of pieces
stackable	boolean	Yes	Whether package is stackable
hazardous_materials	boolean	Yes	Whether contains hazardous materials
hazardous_materials_un_na	string	No	UN/NA identification number for hazardous materials (e.g., 'UN1203', 'NA1993')
hazardous_materials_shipping_name	string	No	Official shipping name of the hazardous material (e.g., 'Gasoline', 'Combustible liquid, n.o.s.')
hazardous_materials_hazard_class	string	No	Hazard class classification (e.g., '3', '8', '9' for flammable liquids, corrosive, misc dangerous goods)
hazardous_materials_packaging_group	string	No	Packaging group level indicating danger level ('I', 'II', 'III' - I being most dangerous)
hazardous_materials_emergncy_name	string	No	Emergency contact person's name responsible for hazardous materials handling and incident response
hazardous_materials_emergncy_phone	string	No	24/7 emergency contact phone number for hazardous materials incidents, spills, or transportation emergencies

API Configuration

REST API URL

API Token

Request Examples

JSON

{
  "shop": "",
  "shipment_from": {
    "address_line1": "8825 Perimeter Park Boulevard",
    "city": "Jacksonville",
    "stateCode": "FL",
    "postalCode": "32216",
    "countryCode": "US"
  },
  "shipment_to": {
    "destination": "91283 Grinnell Ln, Coos Bay, Oregon, United States - 97420",
    "name": "test",
    "email": "[email protected]",
    "address_line1": "91283 Grinnell Ln",
    "city": "Coos Bay",
    "state": "Oregon",
    "country": "United States",
    "postalCode": "97420",
    "countryCode": "US",
    "stateCode": "OR",
    "weight": 220,
    "weight_unit": "pound",
    "description": "Acai Juice Powder (Fruit) - 100 Kilograms Enterprise( X 1)"
  },
  "pickup_date": "",
  "pickup_window": {
    "start_at": "08:00:00",
    "end_at": "17:00:00",
    "closing_at": "17:00:00"
  },
  "from_details": {
    "pickup_window": {
      "start_at": "02:00:00",
      "end_at": "04:30:00",
      "closing_at": "10:30:00"
    },
    "company_name": "shipper",
    "contact_name": "shipper",
    "contact_no": "+1 330-899-5862",
    "contact_email": "[email protected]",
    "is_residential": false
  },
  "to_details": {
    "destination_window": {
      "start_at": "02:00:00",
      "end_at": "04:30:00",
      "closing_at": "10:30:00"
    },
    "company_name": "D4W-Solutions",
    "contact_name": "Nick",
    "contact_no": "+1 330-931-5863",
    "contact_email": "[email protected]",
    "is_residential": false
  },
  "packages": [
    {
      "quantity": 1,
      "type": "Box",
      "class": "60",
      "weight": "10",
      "weight_unit": "pound",
      "length": "5",
      "width": "5",
      "height": "5",
      "dimension_unit": "inch",
      "description": "Test",
      "pieces": 1,
      "stackable": false,
      "hazardous_materials": true,
      "hazardous_materials_un_na": "UN1203",
      "hazardous_materials_shipping_name": "Gasoline",
      "hazardous_materials_hazard_class": "3",
      "hazardous_materials_packaging_group": "I",
      "hazardous_materials_emergncy_name": "Test",
      "hazardous_materials_emergncy_phone": "+1 330-899-5862"
    }
  ],
  "options": [],
  "order_id": null,
  "rate_id": "983e7780-954d-4824-a96e-69359cdfbf06",
  "service_code": "58b38efc-ecbe-428e-95e4-0b5d68223939",
  "uuid": "bac3cbc4-3bf9-4d70-b977-c27173d40ceb",
  "rate_type": "shipengine_rates",
  "company_name": "UPS",
  "rate_price": 29.84,
  "rate_currency": "USD",
  "estimate_days": "4 DAY",
  "currency": "USD",
  "order_fulfilled_status": true,
  "service_type": "UNITED PARCEL SERVICE",
  "order_reference_code": "PO#123456"
}

Code Examples

JAVASCRIPT

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

import fetch from "node-fetch";

async function bookShipment() {
  const response = await fetch("https://api.shipduo.com/api/shipments/book-shipment", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": "Bearer ",
    },
    body: JSON.stringify({
      // Request body from the example above
      {
  "shop": "",
  "shipment_from": {
    "address_line1": "8825 Perimeter Park Boulevard",
    "city": "Jacksonville",
    "stateCode": "FL",
    "postalCode": "32216",
    "countryCode": "US"
  },
  "shipment_to": {
    "destination": "91283 Grinnell Ln, Coos Bay, Oregon, United States - 97420",
    "name": "test",
    "email": "[email protected]",
    "address_line1": "91283 Grinnell Ln",
    "city": "Coos Bay",
    "state": "Oregon",
    "country": "United States",
    "postalCode": "97420",
    "countryCode": "US",
    "stateCode": "OR",
    "weight": 220,
    "weight_unit": "pound",
    "description": "Acai Juice Powder (Fruit) - 100 Kilograms Enterprise( X 1)"
  },
  "pickup_date": "",
  "pickup_window": {
    "start_at": "08:00:00",
    "end_at": "17:00:00",
    "closing_at": "17:00:00"
  },
  "from_details": {
    "pickup_window": {
      "start_at": "02:00:00",
      "end_at": "04:30:00",
      "closing_at": "10:30:00"
    },
    "company_name": "shipper",
    "contact_name": "shipper",
    "contact_no": "+1 330-899-5862",
    "contact_email": "[email protected]",
    "is_residential": false
  },
  "to_details": {
    "destination_window": {
      "start_at": "02:00:00",
      "end_at": "04:30:00",
      "closing_at": "10:30:00"
    },
    "company_name": "D4W-Solutions",
    "contact_name": "Nick",
    "contact_no": "+1 330-931-5863",
    "contact_email": "[email protected]",
    "is_residential": false
  },
  "packages": [
    {
      "quantity": 1,
      "type": "Box",
      "class": "60",
      "weight": "10",
      "weight_unit": "pound",
      "length": "5",
      "width": "5",
      "height": "5",
      "dimension_unit": "inch",
      "description": "Test",
      "pieces": 1,
      "stackable": false,
      "hazardous_materials": true,
      "hazardous_materials_un_na": "UN1203",
      "hazardous_materials_shipping_name": "Gasoline",
      "hazardous_materials_hazard_class": "3",
      "hazardous_materials_packaging_group": "I",
      "hazardous_materials_emergncy_name": "Test",
      "hazardous_materials_emergncy_phone": "+1 330-899-5862"
    }
  ],
  "options": [],
  "order_id": null,
  "rate_id": "983e7780-954d-4824-a96e-69359cdfbf06",
  "service_code": "58b38efc-ecbe-428e-95e4-0b5d68223939",
  "uuid": "bac3cbc4-3bf9-4d70-b977-c27173d40ceb",
  "rate_type": "shipengine_rates",
  "company_name": "UPS",
  "rate_price": 29.84,
  "rate_currency": "USD",
  "estimate_days": "4 DAY",
  "currency": "USD",
  "order_fulfilled_status": true,
  "service_type": "UNITED PARCEL SERVICE",
  "order_reference_code": "PO#123456"
}
    }),
  });

  if (!response.ok) {
    throw new Error(`Error: ${response.status}`);
  }

  const data = await response.json();
  console.log(data);
}

bookShipment().catch(console.error);

Response Examples

Small Parcel Response

JSON

{
  "status": "success",
  "message": "Operation succeeded.",
  "data": {
    "company_name": "UPS",
    "title": "UPS (UPS Ground)",
    "pdf_link": "https://testing-project.nyc3.digitaloceanspaces.com/d4w/684d418a39bde.pdf",
    "price": "$29.84",
    "estimate_days": "4 DAY",
    "is_custom_order": true,
    "tracking_url": "https://www.ups.com/track?loc=en_US&tracknum=1ZV017145308553722&requester=ST/trackdetails",
    "tracking_number": "1ZV017145308553722"
  }
}

Response Format

Success Response Structure

Parameter	Type	Description
status	string	Response status ("success" or "error")
message	string	Response message
data	object	Booking confirmation data

Response Data Object

Parameter	Type	Description
company_name	string	Carrier company name
title	string	Service title with carrier details
pdf_link	string	URL to shipping label/BOL PDF
price	string	Formatted shipping cost
estimate_days	string	Estimated delivery time
is_custom_order	boolean	Whether this is a custom order
tracking_url	string	Tracking URL for track order
tracking_number	string	Tracking Number for track order

Error Response

JSON

{
  "status": "error",
  "message": "Error description here",
  "data": null
}

HTTP Status Codes

200OK - Successful booking

400Bad Request - Invalid request parameters

401Unauthorized - Authentication failed

422Unprocessable Entity - Validation errors

500Internal Server Error - Server error

Important Notes

Prerequisites: Before booking, you must first call the rates API to obtain the required rate information (rate_id, uuid, service_code, etc.).
Rate Types:
- Use shipengine_rates for Small Parcel shipments
- Use shipengine_ltl_rates for LTL shipments
Service Code: Required for Small Parcel shipments, not used for LTL shipments.
NMFC Code: Required for LTL shipments to classify freight type.
PDF Documents:
- Small Parcel bookings return shipping labels
- LTL bookings return Bill of Lading (BOL) documents
Weight Limits:
- Small Parcel: Typically under 150 lbs
- LTL: Over 150 lbs up to full truckload
Pickup Windows: Ensure pickup times are within carrier service hours and allow sufficient time for pickup scheduling.

Workflow

Get shipping rates using the rates API
Select desired rate and service
Extract required rate information (rate_id, uuid, service_code, etc.)
Submit booking request with complete shipment details
Receive confirmation with tracking information and shipping documents