Get Shipping Rates
POST/api/fulfillment-orders/:fulfillmentOrder/shippo/rates
Creates a Shippo shipment for the given parcels (from the warehouse's sender address to the fulfillment order's ship-to address) and returns its rates. The Shippo instance and the ship-from address are resolved from the fulfillment order (its Shippo instance and its warehouse's sender-address mapping) — they are never passed by the client. Requires a token with the orders read/write scope.
orders:writeGrant this scope to your token under Settings → Developer → Personal Access Tokens.
Body fields:
- parcels (array, required): 1–20 parcels. Multi-parcel shipments buy one label per parcel.
- parcels..length, parcels..width, parcels.*.height (number, required): greater than 0.
- parcels.*.distance_unit (string, required): in or cm.
- parcels.*.weight (number, required): greater than 0.
- parcels.*.mass_unit (string, required): lb, oz, kg or g.
- carrier_account_ids (array of strings, optional): limit rating to these Shippo carrier account object ids (max 64 characters each).
Response: shipment_object_id (echo it back when purchasing), rates sorted cheapest purchasable first, messages (Shippo's carrier messages verbatim, plus notices such as an incomplete rate list), is_complete (false when some carriers did not answer in time — re-quote to retry), is_test and integration_instance_id. Each rate has object_id, shipment, carrier, carrier_name, provider_image_75, servicelevel_token, servicelevel_name, amount/currency, amount_local/currency_local (amounts are strings), estimated_days, duration_terms, arrives_by, attributes (e.g. CHEAPEST, FASTEST, BESTVALUE), carrier_account, shipping_method_id (the SKU.io shipping method mapped to this service level, or null), purchasable and unavailable_reason (USPS rates are not purchasable for multi-parcel shipments).
Returns 422 {message, reason} when the fulfillment order cannot use Shippo labels. reason is one of: no_instance (Shippo is not connected), fulfillment_order_closed (the fulfillment order is no longer open), warehouse_unmapped (its warehouse has no usable Shippo sender address), international (only US ship-to addresses are supported), address_incomplete (the ship-to address is missing a required field). Shippo client-side refusals (including a rejected token) return 422 {message, messages[]}; Shippo throttling, Shippo server errors and connection failures return 502. Returns 422 with field errors when validation fails, 404 for an unknown fulfillment order.
Authentication: Requires a Bearer token.
Request
Responses
- 200
- 401
- 403
- 404
- 422
- 429
- 502
OK
Response Headers
Unauthenticated — the bearer token is missing, revoked, expired, or malformed. Never retry automatically; fix the credential. See the Errors guide.
Forbidden — the token lacks a required scope, the endpoint is not available to API tokens, or the user behind the token lacks the permission. A human must adjust the token scopes or user permissions; do not retry.
Not Found
Response Headers
Unprocessable Entity
Response Headers
Rate limited — platform limit is 1,000 requests/min; individual tokens may carry lower limits. Honor the Retry-After header before retrying. See the Rate Limits guide.
Bad Gateway