How to get Shipping Rates
Compare live prices and delivery times from every courier on your account in one call, with taxes and duties included, then choose the best option for each order.
What it does
Returns every available courier option for a parcel
You need
From address, to address, parcel weight and items
Scope
public.rate:readNext step
Create a shipment with the chosen
courier_service.idOn this page
When to use it
Rates at checkout
Show buyers cheapest, fastest and best-value options. Checkout guide →
Auto-select a courier
Pick a courier in your backend automatically before you buy the label.
Landed cost
Quote shipping, tax and duty together for international orders.
How it works
Step 1
Request rates
POST /rates
→
Step 2
Pick a rate
courier_service.id
→
Step 3
Create shipment
POST /shipments
→
Step 4
Buy label
POST /shipments/{id}/label
Easyship gets live prices from every eligible courier service, applies your shipping rules (if enabled), and ranks the results for you.
Request rates
cURL
curl -X POST https://public-api.easyship.com/2024-09/rates \
-H "Authorization: Bearer $EASYSHIP_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"origin_address": {
"line_1": "1 Market St", "city": "San Francisco", "state": "CA",
"postal_code": "94105", "country_alpha2": "US"
},
"destination_address": {
"line_1": "10 Downing Street", "city": "London",
"postal_code": "SW1A 2AA", "country_alpha2": "GB"
},
"incoterms": "DDU",
"courier_settings": { "apply_shipping_rules": true, "show_courier_logo_url": true },
"shipping_settings": { "units": { "weight": "kg", "dimensions": "cm" } },
"parcels": [{
"total_actual_weight": 1.2,
"box": { "length": 30, "width": 20, "height": 10 },
"items": [{
"description": "T-shirt", "category": "fashion", "hs_code": "61091000",
"quantity": 2, "declared_currency": "USD", "declared_customs_value": 25
}]
}]
}'
Shipping to or within the US, CA, MX or AU? Always send
city and state for both addresses. Some couriers won't return a rate without them.Read and pick a rate
The response has a rates array with one entry per courier service:
Response
{
"rates": [{
"courier_service": {
"id": "01563646-58c1-4607-8fe0-cae3e33c0001",
"name": "DHL Express Worldwide",
"umbrella_name": "DHL"
},
"currency": "USD",
"total_charge": 38.40,
"shipment_charge": 32.00,
"fuel_surcharge": 6.40,
"min_delivery_time": 2,
"max_delivery_time": 4,
"estimated_import_tax": 10.00,
"estimated_import_duty": 0.0,
"cost_rank": 2.0,
"delivery_time_rank": 1.0,
"value_for_money_rank": 1.0,
"easyship_rating": 4.0
}]
}
| Field | What it tells you |
|---|---|
courier_service.id | What you pass to Create a Shipment |
total_charge | What you pay (shipping + surcharges + fees) |
min_delivery_time / max_delivery_time | Delivery estimate in working days |
estimated_import_tax / estimated_import_duty | What the buyer pays on import (see Taxes and Duties) |
cost_rank = 1 | 💰 Cheapest |
delivery_time_rank = 1 | ⚡ Fastest |
value_for_money_rank = 1 | ⭐ Best value |
Simple checkout pattern: show three options, labelled Cheapest, Fastest and Best value, using the three rank fields.
Useful options
| Option | Effect |
|---|---|
incoterms: "DDP" | Taxes and duties are added to the price you pay, so the buyer pays nothing on delivery |
calculate_tax_and_duties: false | Skips T&D estimates, so the call isn't billed as T&D (DDU only) |
set_as_residential | Applies residential delivery surcharges where the courier charges them |
insurance | Adds the insurance fee to each rate |
courier_settings.apply_shipping_rules | Applies your shipping rules (e.g. hide a courier, force a box) |
filter_options | Filters the returned rates |
FAQ and troubleshooting
Why am I getting an empty
rates array?The usual causes are a missing
city or state, a weight over the courier's limit, or no courier enabled for that route. Check your enabled couriers in the dashboard.Why does sandbox show fewer couriers?
Sandbox returns sample couriers only. Use production to see your full list.
Is the price held after I request it?
No. Rates are live. If time has passed, request rates again before you buy the label.
How do I resolve a
422 invalid_content?A required field is missing.
origin_address, destination_address and parcels are required. The details array names the field.Updated 1 day ago
Did this page help you?