Skip to content

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#

POST/api/v1/quotesScope quotes:write
Request
curl -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"
  }'
Response
{
	"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:

JSON
{
	"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.

JSON
"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:

Request
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 }'
Response
{
	"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 service to offer a choice of carriers for each service level. The rates with cheapest_for_service: true are exactly the ones you get without the flag.
  • Every rate books the same way. Pass its quote_id to POST /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/bulk takes the flag too, and so does the MCP tool quote_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#

POST/api/v1/quotes/bulkScope quotes:write
Request
curl -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", … }
    ]
  }'
Response
{
  "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_failed listing every problem, each field prefixed 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 error with one of the codes above, and the others carry rates. rated and failed save 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#

GET/api/v1/quotesScope quotes:read
Shell
curl "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.

GET/api/v1/quotes/{quoteId}Scope quotes:read
Request
curl https://app.shipeasyco.com/api/v1/quotes/cm2k8r9f2… \
  -H "Authorization: Bearer $SHIPEASY_API_KEY"
Response
{
	"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_at before booking and re-quote if it has passed.
  • Just book, and treat 410 quote_expired as "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.