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
JSON
headers: {
"Authorization": "Bearer {YOUR_API_KEY}",
"Content-Type": "application/json"
}Request Parameters
Common Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| id | integer | Yes | Provider ID obtained from the Provider List API |
| type | string | Yes | Shipment type. Options: "small_parcel" or "ltl" |
| pickup_date | string | Yes | Pickup date in YYYY-MM-DD format |
| options | array | No | Additional shipping options (see Provider List API for available options) |
| fetch_rates_random_key | string | Yes | Unique identifier for the rate fetch request |
Shipment Origin (shipment_from)
| 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 | Two-letter state code (e.g., 'FL') |
| postalCode | string | Yes | ZIP/postal code |
| countryCode | string | Yes | Two-letter country code (e.g., 'US') |
Shipment Destination (shipment_to)
| Parameter | Type | Required | Description |
|---|---|---|---|
| destination | string | Yes | Full formatted destination address |
| company | string | No | Company name |
| name | string | Yes | Recipient name |
| 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 | Full state name |
| country | string | Yes | Full country name |
| postalCode | string | Yes | ZIP/postal code |
| countryCode | string | Yes | Two-letter country code |
| stateCode | string | Yes | Two-letter state code |
| weight | number | Yes | Total shipment weight |
| weight_unit | string | Yes | Weight unit (e.g., "pound", "kilogram") |
| description | string | Yes | Description of the shipment contents |
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 Details (packages)
| Parameter | Type | Required | Description |
|---|---|---|---|
| quantity | integer | Yes | Number of packages of this type |
| type | string | Yes | Package type (e.g., "Pallet", "Box") |
| class | string | Yes | Freight class (for LTL) or package class |
| nmfc | string | Yes | National Motor Freight Classification code |
| weight | string | Yes | Individual package weight |
| weight_unit | string | Yes | Weight unit for this package |
| length | string | Yes | Package length |
| width | string | Yes | Package width |
| height | string | Yes | Package height |
| dimension_unit | string | Yes | Dimension unit (e.g., "inch", "cm") |
| description | string | Yes | Package contents description |
| pieces | integer | Yes | Number of pieces in this package |
| stackable | boolean | Yes | Whether the package can be stacked |
| hazardous_materials | boolean | Yes | Whether package 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
Request Examples
JSON
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
JAVASCRIPT
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
JSON
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
| Parameter | Type | Description |
|---|---|---|
| status | boolean | Indicates if the request was successful |
| message | string | Human-readable status message |
| data | array | Array of available shipping rates |
Rate Object Structure
| Parameter | Type | Description |
|---|---|---|
| logo | string | URL to the carrier's logo image |
| company_name | string | Full carrier company name |
| title | string | Display title for the carrier |
| delivery_service | string | Specific service type offered |
| price | number | Shipping cost in the specified currency |
| currency | string | Currency code (e.g., "USD") |
| currency_symbol | string | Currency symbol (e.g., "$") |
| time.time | integer | Estimated delivery time value |
| time.unit | string | Time unit ("DAY", "HOUR", etc.) |
| provider | string | Internal provider identifier |
| type | string | Rate type classification |
| service_code | string | Carrier-specific service code |
| shipment_service_code | string | Service code for shipment booking |
| shipment_service_name | string | Human-readable service name |
| id | string | Unique rate identifier |
| shop_own_rate | boolean | Whether this is a negotiated rate |
| uuid | string | Unique UUID for this rate quote |
| cost | string | Base64 encoded cost information |
Error Response
JSON
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.