Quoting
Contents 26 pages
Rating a lane returns one priced option per service offered on it — No
Signature Required, Curbside Delivery, Room of Choice, White Glove, White Glove
with Assembly — each from the carrier that sells it cheapest, cheapest first.
Each rate's description says what its service includes. Send
include_all_carriers: true to also get every other carrier's price for each
service. Each rate is saved as a quote with an id, and that id is what you book.
Every price, id and date in the examples on this page is illustrative, made up for the example: a real rate depends on your lane, freight and service, and only a signed-in request returns one.
Rate a lane#
/api/v1/quotesScope quotes:writecurl -X POST https://app.shipeasyco.com/api/v1/quotes \
-H "Authorization: Bearer $SHIPEASY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"origin": {
"city": "Elk Grove Village",
"state": "IL",
"postal_code": "60007"
},
"destination_state": "TX",
"destination_postal_code": "75201",
"handling_units": [
{
"package_type": "pallet",
"length_in": "48",
"width_in": "40",
"height_in": "52",
"weight_lbs": "780",
"quantity": "2",
"description": "Palletized machine parts"
}
],
"pickup_date": "2026-11-17"
}'const res = await fetch("https://app.shipeasyco.com/api/v1/quotes", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.SHIPEASY_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
origin: { city: "Elk Grove Village", state: "IL", postal_code: "60007" },
destination_state: "TX",
destination_postal_code: "75201",
handling_units: [
{
package_type: "pallet",
length_in: "48",
width_in: "40",
height_in: "52",
weight_lbs: "780",
quantity: "2",
description: "Palletized machine parts",
},
],
pickup_date: "2026-11-17",
}),
});
const result = await res.json();import os
import requests
res = requests.post(
"https://app.shipeasyco.com/api/v1/quotes",
headers={"Authorization": f"Bearer {os.environ['SHIPEASY_API_KEY']}"},
json={
"origin": {"city": "Elk Grove Village", "state": "IL", "postal_code": "60007"},
"destination_state": "TX",
"destination_postal_code": "75201",
"handling_units": [
{
"package_type": "pallet",
"length_in": "48",
"width_in": "40",
"height_in": "52",
"weight_lbs": "780",
"quantity": "2",
"description": "Palletized machine parts",
}
],
"pickup_date": "2026-11-17",
},
)
result = res.json(){
"object": "quote_result",
"pickup_date": "2026-11-18",
"lane": {
"origin": {
"label": "LA warehouse",
"city": "Los Angeles",
"state": "CA",
"postal_code": "90021",
"residential": false
},
"destination": {
"city": "Rome",
"state": "GA",
"postal_code": "30165",
"residential": true
}
},
"missing_for_booking": ["destination.phone"],
"rates": [
{
"object": "rate",
"quote_id": "cm2k8r9f2…",
"carrier": "CEVA Logistics",
"carrier_scac": "CEVA",
"service": "Curbside Delivery",
"description": "Liftgate + delivery to entrance or receiving area.",
"amount_usd": "1285.00",
"currency": "USD",
"transit_days": 3,
"appointment_required": false,
"expires_at": "2026-11-15T14:03:11.000Z",
"cheapest_for_service": true,
"bookable": true,
"not_bookable_reason": null
},
{
"object": "rate",
"quote_id": "cm2k8r9f3…",
"carrier": "AIT Worldwide Logistics",
"carrier_scac": "AITW",
"service": "White Glove",
"description": "Room of choice + light assembly (≤30 mins).",
"amount_usd": "1341.00",
"currency": "USD",
"transit_days": 4,
"appointment_required": true,
"expires_at": "2026-11-15T14:03:11.000Z",
"cheapest_for_service": true,
"bookable": false,
"not_bookable_reason": "White Glove isn't enabled for this organization yet. Request access in the web app."
}
]
}pickup_date is the day the rates are for: the one you sent, or the earliest
allowed when you sent none. A booking is made for that day — quote again to
change it. lane echoes both ends as rated, and missing_for_booking lists
what a booking would still need beyond quote_id (here the receiver's phone);
empty means quote_id alone books it.
Every rate is already saved. bookable says whether your organization can book
it, and not_bookable_reason why not — White Glove or White Glove with
Assembly before ops has approved White Glove for you (one approval covers both),
or the rare rate we could not save (its quote_id is null; rate the
lane again).
appointment_required means the carrier will call ahead to schedule delivery;
it is false on No Signature Required, which is left outside with no
appointment and no signature.
Pick a rate and pass its quote_id to POST /bookings —
you do not re-send the freight to book it.
Shipment coverage is not part of a quote; add insurance when you
book.
Requires quotes:write. Each lane that returns rates counts one against your
daily quote budget, whether one carrier answers or five. A refused lane costs
nothing.
The request#
| Field | ||
|---|---|---|
origin_id |
string | A saved origin's id from GET /origins, instead of origin. Its street and contact ride with the quote. Sending both is 400 validation_failed; an id your organization does not have is 400 validation_failed on origin_id, and nothing is counted. |
origin |
object | Required unless origin_id is sent. city (≤120), state and postal_code are required, with the same rules as the destination fields below, except that a ZIP outside its state gets 400 invalid_request. label (≤80), address1, address2, company (≤120 each), contact_name (≤80), phone (≤32) and email (≤254) ride along so a booking can be made from the quote alone; rating reads only city, state and ZIP. |
destination_state |
string | Required unless destination_id is sent. Two-letter code: one of the 50 states or DC. HI and AK are accepted but not served: 400 destination_not_serviceable (or origin_not_serviceable for an origin there). |
destination_postal_code |
string | Required unless destination_id is sent. Five digits. Not ZIP+4. A ZIP outside destination_state gets 400 freight_invalid. |
destination_id |
string | A saved destination's id from GET /destinations, instead of the two fields above; its ZIP, state, residential flag, street and contact ride with the quote. Send its ZIP too if you like — a different one is 400 validation_failed. |
destination |
object | Who and where it is delivered to: contact_name (≤80), company, address1, address2, city (≤120 each), phone (≤32), email (≤254). Rating never reads it; it rides with the quote so a booking can be made from it alone, and a street is remembered in your address book, as the web app does. Beside destination_id, a sent street replaces the saved one whole and contact fields fill over it. |
handling_units |
array, required | 1–100 units. See below. |
pickup_date |
YYYY-MM-DD |
The collection day; it changes the price, and a quote can only be booked for the day it was rated for. A weekend, a federal holiday or a day inside your pickup lead time is 400 validation_failed on pickup_date, naming the earliest day that works. Omitted, the earliest allowed day is used and returned as pickup_date. |
origin_residential |
boolean | Default false. A residential pickup is a different tariff. |
destination_residential |
boolean | Default false, or the saved destination's flag with destination_id. A residential delivery is a different tariff too. |
include_all_carriers |
boolean | Default false. true adds every other carrier's rate for each service, each marked cheapest_for_service: false and bookable like any rate. Same quote budget: one lane is one quote. |
ref |
string ≤64 | Echoed back on each bulk lane result; POST /quotes accepts it but does not return it. |
Handling units#
| Field | ||
|---|---|---|
package_type |
pallet · box · crate · bundle · roll · drum · bag · piece |
Default pallet. |
length_in, width_in, height_in |
required | Inches, per unit — not the total of the stack. More than 0. |
weight_lbs |
required | Pounds, per unit. More than 0. |
quantity |
required | How many identical units. A whole number, 1 or more: "2.5" fails. |
description |
≤120 chars | What it is. Appears on the BOL. |
hazmat |
object | Declares the unit hazardous. See Hazardous materials. |
Instead of its sizes, a unit may name a model from your catalog with
model_code and quantity; its boxes are rated. See
Quote a model.
Dimensions and weights may be sent as strings ("48", "52.5") or numbers.
Strings are safer: 12.845 is not exactly representable as a float, and freight
is priced on exact numbers. We keep whatever precision you send. A string is
digits with an optional decimal point; a comma is read only as a thousands
separator ("1,200" is 1,200), and anything else in it ("48in", "1e3") is
400 validation_failed on that field.
Limits#
Per handling unit: 600 in on any side, 45,000 lb. Across the whole shipment: 600 pieces.
A request that breaks a limit or a field rule gets 400 validation_failed, with
one entry in issues per problem:
{
"error": {
"type": "invalid_request",
"code": "validation_failed",
"message": "Some fields did not pass validation. See `issues`.",
"issues": [
{
"field": "handling_units[0].length",
"code": "freight.length.too_large",
"message": "Max 600 in."
}
],
"request_id": "req_8d1f6a3c9e2b7045",
"doc_url": "/developers/errors#validation_failed"
}
}The freight rules name the unit and the measure without its suffix:
handling_units[0].length, and likewise width, height, weight and
quantity. The 600-piece cap is reported on handling_units, with code
freight.pieces.too_many. A hazmat field is named under its unit, as
handling_units[0].hazmat.un_number.
Hazardous materials#
Declare a handling unit as hazardous materials with its hazmat object. Only a
carrier with a hazmat rate quotes it, today CEVA, which adds its Hazardous
Materials charge ($75 per shipment, plus margin) to the price; the other
carriers decline the lane. When no carrier will, the lane answers
422 no_rates_available.
"handling_units": [
{
"package_type": "pallet",
"length_in": "48",
"width_in": "40",
"height_in": "40",
"weight_lbs": "600",
"quantity": "1",
"description": "Paint",
"hazmat": {
"un_number": "UN1263",
"hazard_class": "3",
"packing_group": "II",
"proper_shipping_name": "Paint",
"emergency_phone": "800-555-0100"
}
}
]| Field | ||
|---|---|---|
un_number |
required | UN and four digits, e.g. UN1993. Four digits alone are read as UN. An NA number is refused for now, code hazmat.naNumber: the carrier's bill of lading cannot print one yet. |
hazard_class |
required | 2.1, 2.2, 2.3, 3, 4.1, 4.2, 4.3, 5.1, 5.2, 6.1, 8 or 9. Classes 1, 6.2 and 7 are refused. |
packing_group |
I, II or III; omit it or send null when the material has none. |
|
proper_shipping_name |
required | As the shipping papers print it. Max 200 characters. |
emergency_phone |
required | A number answered 24 hours a day while the freight moves. |
A bad field is 400 validation_failed, named as above. Booking a quote with a
declared unit needs hazmat_certified: true on
POST /bookings. Hazmat cannot be
declared on POST /orders/{orderId}/quote, which rates the order's own boxes.
Every carrier's rate#
Each service normally comes back once, from the carrier that sells it cheapest.
To let your customer, or your own checkout, choose the carrier, send
include_all_carriers: true:
curl -X POST https://app.shipeasyco.com/api/v1/quotes \
-H "Authorization: Bearer $SHIPEASY_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "origin": { … }, "destination_state": "TX", "destination_postal_code": "75201",
"destination_residential": true, "handling_units": [ … ],
"include_all_carriers": true }'{
"object": "quote_result",
"rates": [
{
"object": "rate",
"quote_id": "cm2k8r9f2…",
"carrier": "CEVA Logistics",
"service": "Curbside Delivery",
"amount_usd": "1285.00",
"transit_days": 3,
"cheapest_for_service": true
},
{
"object": "rate",
"quote_id": "cm2k8r9f4…",
"carrier": "AIT Worldwide Logistics",
"service": "Curbside Delivery",
"amount_usd": "1340.00",
"transit_days": 2,
"cheapest_for_service": false
},
{
"object": "rate",
"quote_id": "cm2k8r9f5…",
"carrier": "CEVA Logistics",
"service": "Room of Choice",
"amount_usd": "1460.00",
"transit_days": 4,
"cheapest_for_service": true
}
]
}- One list, cheapest first. Group it by
serviceto offer a choice of carriers for each service level. The rates withcheapest_for_service: trueare exactly the ones you get without the flag. - Every rate books the same way. Pass its
quote_idtoPOST /bookings. White Glove still needs your organization to be approved, whichever carrier sells it. - Same budget. A lane is one quote, however many carriers answer.
- Everywhere you rate. Each lane of
POST /quotes/bulktakes the flag too, and so does the MCP toolquote_freight.
When a lane cannot be rated#
A well-formed request can still be refused. POST /quotes answers with the
code's own status:
| Code | Status | |
|---|---|---|
freight_invalid |
400 | The freight or lane cannot be rated as sent — for example, a destination ZIP outside destination_state. |
invalid_request |
400 | The origin ZIP is not in the origin state. |
origin_not_serviceable |
400 | We do not pick up from that origin. |
destination_not_serviceable |
400 | We do not deliver there — Hawaii and Alaska. |
no_rates_available |
422 | No carrier returned a rate. Check the ZIPs, or try another pickup date. |
no_carrier_enabled |
403 | No carrier is enabled for your organization. |
upstream_unavailable |
503 | A carrier system is unreachable. Retry with backoff. |
api_unavailable |
503 | We could not count the lane against your quote budget, so we did not rate it. Retry after a few seconds. |
daily_quota_exceeded |
429 | The daily quote budget is spent. It resets at 00:00 UTC. |
Each code is described on errors.
Rate up to 25 lanes at once#
/api/v1/quotes/bulkScope quotes:writecurl -X POST https://app.shipeasyco.com/api/v1/quotes/bulk \
-H "Authorization: Bearer $SHIPEASY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"lanes": [
{ "ref": "SO-1041", "origin": { … }, "destination_state": "TX", … },
{ "ref": "SO-1042", "origin": { … }, "destination_state": "HI", … }
]
}'{
"object": "bulk_quote_result",
"lanes": [
{ "object": "quote_result", "ref": "SO-1041", "rates": [ … ], "error": null },
{
"object": "quote_result",
"ref": "SO-1042",
"rates": [],
"error": {
"code": "destination_not_serviceable",
"message": "…"
}
}
],
"rated": 1,
"failed": 1
}Results come back in the order you sent the lanes. Set ref on each lane and it
comes back on the matching result — that is how you tie a reply to the order it
came from.
Two behaviours worth knowing:
- Shape errors are all-or-nothing. Send 25 lanes with one malformed ZIP and
you get a single
400 validation_failedlisting every problem, eachfieldprefixed with its lane (lanes[1].destination_postal_code), not 24 quotes and a mystery. Fix and resend. - Rating failures are per-lane. If the shape is fine but a lane cannot be
rated — a ZIP outside its state, a destination we do not serve, no carrier
rate — that lane carries an
errorwith one of the codes above, and the others carry rates.ratedandfailedsave you walking the array.
Idempotency-Key is required — 25 lanes is up to 25 charges against your
quote budget, and a blind retry would spend them twice.
Requires quotes:write. Each lane that returns rates counts one against the
quote budget, so a 25-lane call costs at most 25 quotes and one request; a
failed lane costs nothing. If the budget runs out part-way, the lanes past it
are not rated and carry error.code daily_quota_exceeded.
If we cannot count the call against your budget, the whole call is refused with
503 api_unavailable and Retry-After before any lane is rated, and nothing is
spent. Retry it with the same Idempotency-Key: the refusal is not stored.
Read quotes back#
/api/v1/quotesScope quotes:readcurl "https://app.shipeasyco.com/api/v1/quotes?state=bookable&limit=50" \
-H "Authorization: Bearer $SHIPEASY_API_KEY"Newest first, paged like every list — see pagination.
state is all (the default), bookable, expired or booked; carrier is
an exact match on the carrier name, e.g. CEVA Logistics. The list holds quotes
rated in the web app and through the API. A Shopify store's key lists the
store's quotes, from its Shopify app and through the API.
/api/v1/quotes/{quoteId}Scope quotes:readcurl https://app.shipeasyco.com/api/v1/quotes/cm2k8r9f2… \
-H "Authorization: Bearer $SHIPEASY_API_KEY"{
"object": "quote",
"id": "cm2k8r9f2…",
"reference": "QT-K7QD9M3",
"state": "bookable",
"carrier": "CEVA Logistics",
"carrier_scac": "CEVA",
"service": "Curbside Delivery",
"service_level": "LIFTGATE",
"amount_usd": "1285.00",
"currency": "USD",
"transit_days": 3,
"lane": {
"origin": {
"label": "Montebello",
"city": "Montebello",
"state": "CA",
"postal_code": "90640",
"residential": false
},
"destination": {
"city": "Rome",
"state": "GA",
"postal_code": "30165",
"residential": false
}
},
"missing_for_booking": ["origin.phone", "destination.name"],
"cheapest_for_service": true,
"expires_at": "2026-11-15T14:03:11.000Z",
"shipment_id": null,
"created_at": "2026-11-12T14:03:11.000Z"
}state is bookable, expired or booked. shipment_id is set once the quote
has been booked, which is the cheapest way to ask "did this get shipped?".
lane is the lane the quote was rated for, as places: city, state, ZIP and
whether each end is residential, never a name or a street. It is null on an
older quote whose rating didn't keep both ends. missing_for_booking is what a
booking of it would still need, as POST /quotes answers; it is null when the
quote's request can't be read back, and such a quote is rated again to book it
over the API.
cheapest_for_service is false only on another carrier's rate, saved because
the lane was rated with include_all_carriers.
Both need quotes:read. Reading costs nothing against your quote budget — only
rating does.
Quotes expire#
A rate stays bookable for 72 hours from when it was rated, unless ShipEasy has
agreed a different price and date with you; expires_at is always the deadline
booking enforces. Booking after it returns 410 quote_expired.
Two ways to handle it, and the second is better:
- Check
expires_atbefore booking and re-quote if it has passed. - Just book, and treat
410 quote_expiredas "re-quote and book the new rate". There is no penalty for trying, and it is one fewer round trip in the common case.
If the carrier's price moves between quoting and booking, the booking is refused
with 409 price_changed rather than charged at the new number. You are never
charged an amount you were not quoted.