Fetch Rates API

Retrieve shipping rates from carriers based on shipment details

POST/api/shipments/fetch-ratesSmall Parcel & LTL

Description

The Fetch Rates API allows you to retrieve shipping rates from various carriers by providing shipment details and a provider ID. This endpoint supports both Small Parcel and Less Than Truckload (LTL) shipments.

Authentication

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

Request Parameters

Common Parameters

ParameterTypeRequiredDescription
idintegerYesProvider ID obtained from the Provider List API
typestringYesShipment type. Options: "small_parcel" or "ltl"
pickup_datestringYesPickup date in YYYY-MM-DD format
optionsarrayNoAdditional shipping options (see Provider List API for available options)
fetch_rates_random_keystringYesUnique identifier for the rate fetch request

Shipment Origin (shipment_from)

ParameterTypeRequiredDescription
address_line1stringYesPrimary address line
address_line2stringNoSecondary address line
citystringYesCity name
stateCodestringYesTwo-letter state code (e.g., 'FL')
postalCodestringYesZIP/postal code
countryCodestringYesTwo-letter country code (e.g., 'US')

Shipment Destination (shipment_to)

ParameterTypeRequiredDescription
destinationstringYesFull formatted destination address
companystringNoCompany name
namestringYesRecipient name
emailstringYesRecipient email address
phonestringNoRecipient phone number
address_line1stringYesPrimary address line
address_line2stringNoSecondary address line
citystringYesCity name
statestringYesFull state name
countrystringYesFull country name
postalCodestringYesZIP/postal code
countryCodestringYesTwo-letter country code
stateCodestringYesTwo-letter state code
weightnumberYesTotal shipment weight
weight_unitstringYesWeight unit (e.g., "pound", "kilogram")
descriptionstringYesDescription of the shipment contents

Shipper Details (from_details)

ParameterTypeRequiredDescription
pickup_window.start_atstringYesPickup window start time (HH:MM:SS format)
pickup_window.end_atstringYesPickup window end time (HH:MM:SS format)
pickup_window.closing_atstringYesFacility closing time (HH:MM:SS format)
company_namestringYesShipper company name
contact_namestringYesShipper contact person name
contact_nostringYesShipper contact phone number
contact_emailstringYesShipper contact email address
is_residentialbooleanYesWhether the pickup location is residential

Consignee Details (to_details)

ParameterTypeRequiredDescription
destination_window.start_atstringYesPickup window start time (HH:MM:SS format)
destination_window.end_atstringYesPickup window end time (HH:MM:SS format)
destination_window.closing_atstringYesFacility closing time (HH:MM:SS format)
company_namestringYesConsignee company name
contact_namestringYesConsignee contact person name
contact_nostringYesConsignee contact phone number
contact_emailstringYesConsignee contact email address
is_residentialbooleanYesWhether the delivery location is residential

Package Details (packages)

ParameterTypeRequiredDescription
quantityintegerYesNumber of packages of this type
typestringYesPackage type (e.g., "Pallet", "Box")
classstringYesFreight class (for LTL) or package class
nmfcstringYesNational Motor Freight Classification code
weightstringYesIndividual package weight
weight_unitstringYesWeight unit for this package
lengthstringYesPackage length
widthstringYesPackage width
heightstringYesPackage height
dimension_unitstringYesDimension unit (e.g., "inch", "cm")
descriptionstringYesPackage contents description
piecesintegerYesNumber of pieces in this package
stackablebooleanYesWhether the package can be stacked
hazardous_materialsbooleanYesWhether package contains hazardous materials
hazardous_materials_un_nastringNoUN/NA identification number for hazardous materials (e.g., 'UN1203', 'NA1993')
hazardous_materials_shipping_namestringNoOfficial shipping name of the hazardous material (e.g., 'Gasoline', 'Combustible liquid, n.o.s.')
hazardous_materials_hazard_classstringNoHazard class classification (e.g., '3', '8', '9' for flammable liquids, corrosive, misc dangerous goods)
hazardous_materials_packaging_groupstringNoPackaging group level indicating danger level ('I', 'II', 'III' - I being most dangerous)
hazardous_materials_emergncy_namestringNoEmergency contact person's name responsible for hazardous materials handling and incident response
hazardous_materials_emergncy_phonestringNo24/7 emergency contact phone number for hazardous materials incidents, spills, or transportation emergencies
API Configuration
Request Examples
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
{
  "id": 7,
  "type": "small_parcel",
  "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": "yeheskel",
    "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)"
  },
  "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": "Pallet",
      "class": "60",
      "nmfc": "123456",
      "weight": "9",
      "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"
    }
  ],
  "pickup_date": "",
  "options": [],
  "fetch_rates_random_key": "a8c1bd31-a66f-42fa-844d-3415e5e17a0d"
}

Code Examples

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
import fetch from "node-fetch";

async function fetchRates() {
  const response = await fetch("https://api.shipduo.com/api/shipments/fetch-rates", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": "Bearer ",
    },
    body: JSON.stringify({
      // Request body from the example above
      {
  "id": 7,
  "type": "small_parcel",
  "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": "yeheskel",
    "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)"
  },
  "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": "Pallet",
      "class": "60",
      "nmfc": "123456",
      "weight": "9",
      "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"
    }
  ],
  "pickup_date": "",
  "options": [],
  "fetch_rates_random_key": "a8c1bd31-a66f-42fa-844d-3415e5e17a0d"
}
    }),
  });

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

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

fetchRates().catch(console.error);

Response Examples

Small Parcel Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
{
  "status": true,
  "message": "Operation succeeded.",
  "data": [
    {
      "logo": "https://api.shipduo.com/asset/shipping/ups.webp",
      "company_name": "UPS",
      "title": "UPS",
      "delivery_service": "UPS Ground",
      "price": 33.26,
      "currency": "USD",
      "currency_symbol": "$",
      "time": {
        "time": 9,
        "unit": "DAY"
      },
      "provider": "ups",
      "type": "shipengine_rates",
      "service_code": "03",
      "shipment_service_code": "03",
      "shipment_service_name": "UPS Ground",
      "id": "34uEEYnijNQOZChuUgBLCGSbv0kIy3wE-03",
      "shop_own_rate": true,
      "uuid": "53249e41-6a2b-4c90-a303-81490f1da158",
      "cost": "MzAuMjQ="
    }
  ]
}

Response Format

Success Response Structure

ParameterTypeDescription
statusbooleanIndicates if the request was successful
messagestringHuman-readable status message
dataarrayArray of available shipping rates

Rate Object Structure

ParameterTypeDescription
logostringURL to the carrier's logo image
company_namestringFull carrier company name
titlestringDisplay title for the carrier
delivery_servicestringSpecific service type offered
pricenumberShipping cost in the specified currency
currencystringCurrency code (e.g., "USD")
currency_symbolstringCurrency symbol (e.g., "$")
time.timeintegerEstimated delivery time value
time.unitstringTime unit ("DAY", "HOUR", etc.)
providerstringInternal provider identifier
typestringRate type classification
service_codestringCarrier-specific service code
shipment_service_codestringService code for shipment booking
shipment_service_namestringHuman-readable service name
idstringUnique rate identifier
shop_own_ratebooleanWhether this is a negotiated rate
uuidstringUnique UUID for this rate quote
coststringBase64 encoded cost information

Error Response

1
2
3
4
5
{
  "status": false,
  "message": "Error description here",
  "data": null
}

HTTP Status Codes

200OK - Successful provider list retrieval
400Bad Request - Invalid request parameters
401Unauthorized - Authentication failed
422Unprocessable Entity - Validation errors
500Internal Server Error - Server error

Integration Notes

  • Provider ID: Obtain valid provider IDs from the Provider List API before making rate requests
  • Rate Caching: Rates may be cached for a short period. Use the fetch_rates_random_key to ensure fresh quotes
  • Pickup Windows: Ensure pickup windows align with carrier operating hours
  • Weight Limits: Different carriers have varying weight and dimension limits
  • Rate Selection: Use the returned uuid or id to reference specific rates in subsequent booking requests

Rate Limiting

This endpoint is subject to rate limiting. Refer to your API plan for specific limits.

Support

For technical support or questions about this API, contact our development team.