Get Shipment Rates

mailhub_get_shipment_rates

Get the carrier Rates available for one Shipment, so a Rate can be chosen and bought.

Permission and safety

Changes data	No
Confirmation	Not required
Spends funds	No
Permission	Update access to Orders

This read needs update access

Rating is the one read-shaped tool that is not covered by view access. A user who can view Orders but not update them can list and read Orders, and can get a Label link, but is refused here. See Before You Connect for the full split.

Input

Field	Type	Required	Notes
shipmentId	string	Yes	The Shipment's UUID. Checked for shape before the call is made.

Example input

{
  "shipmentId": "22222222-2222-2222-2222-222222222222"
}

Output

Field	Contents
rates	The available Rates
totalCount	How many Rates were returned
carrierCount	How many carriers they came from

Each Rate carries its own identifier — the value mailhub_buy_label needs — along with the carrier and service information the carrier returned, the price and its currency, and delivery estimate fields where the carrier supplies them. Two presentation fields are added for readability: deliveryLabel, a phrase such as "1 day" or "Same-day delivery", and isSameDayDelivery when that applies.

The three fields above are the whole top level. The fields inside each Rate are described rather than pinned: treat them as what a Rate carries, not as a complete stable list to code against.

Prices are carried through exactly as Mailhub holds them; they are never passed through a floating-point value on the way to you.

Rules and common tool-specific errors

No status preparation is needed

Rating works for an Order in any status. You do not need to move the Order to Packed, or to any other status, before asking for Rates. Older material that described a Packed prerequisite is not correct. See Order Statuses for the full model.

• An empty result is a normal answer. No Rates means no carrier priced this Shipment — check the parcel, the addresses, and which carriers the account has configured. It is not an error condition.
• Rates reflect the carriers already available to your account. MCP cannot enable or configure a carrier.
• A Rate is a point-in-time quote. If it has gone stale by the time it is bought, the purchase is refused and you rate again.

Code	What it means	Retrying
MCP_INVALID_UUID	shipmentId is not a UUID	No — fix the value
A correctable carrier rejection	The carrier declined the Shipment as described — usually an address or parcel problem the message names	Yes, after correcting it
A carrier being unavailable	The carrier could not be reached right now	Yes, shortly

Access and shared failures live in Errors & Troubleshooting.

Next

• mailhub_buy_label — buy the Label for a Rate returned here.
• Working with Labels — where rating sits in the Label workflow.