`get_shipping_rates`

Updated May 29, 20262 min read

Get carrier rate quotes for a shipment-like payload. Returns eligible carrier-account options with estimated cost, service details, and any rate-calculation errors.

The right tool when the agent needs to quote — checkout flows, rate-shopping, or a customer asking "how much will this cost?". Works from raw order data — no existing shipment_id needed.

Parameters

Name	Type	Required	Description
`tenantId`	string	Yes	The tenant.
`shipment`	object	Yes	Shipment-like payload (same shape as `create_shipment`).
`include_errors`	boolean	No	Include carrier-side / costing errors in the response. Defaults to `true` — useful for debugging unavailable carriers.
`include_breakdown`	boolean	No	Include cost breakdown entries when available. Defaults to `true`.
`include_markup`	boolean	No	Include markup-adjusted rates when available. Defaults to `false`.
`select`	string	No	json-mask expression to trim the response.

The `shipment` payload

Same shape as the shipment payload on create_shipment. For reliable quotes, populate at minimum:

merchant — drives carrier-account scoping.
pickup — location id or full address.
dropoff — full address with country / postcode.
parcels — quantities, weights, dimensions.
payment — currency (and payment_on_delivery for COD).
delivery_type and order_type if rules depend on them.
items — for cross-border / customs-impacted quotes.

Returns

{
  "rates": [
    {
      "carrier_account_id": "…",
      "carrier_account_name": "…",
      "carrier": "…",
      "service_level": "…",
      "estimated_cost": { "amount": 28, "currency": "AED" },
      "breakdown": [...],          // when include_breakdown=true
      "markup": { ... }            // when include_markup=true
    },
    …
  ],
  "errors": [...]                  // when include_errors=true
}

Why `include_errors` defaults to true

When a carrier is unavailable for a quote, knowing why is often more valuable than the rate itself ("DHL excluded this route by rule", "Aramex returned an error for this postcode"). The default surfaces those reasons.

Example agent prompts

"What carriers can ship to Riyadh, and how much?"

get_shipping_rates(
  tenantId="…",
  shipment={
    "merchant": "…",
    "pickup": { "location_id": "DXB-WH-01" },
    "dropoff": {
      "address1": "25 Maple Street",
      "city": "Riyadh",
      "country": "SA",
      "postcode": "11564"
    },
    "parcels": [{ "quantity": 1, "weight": 1.5 }],
    "payment": { "currency": "AED" }
  }
)

"Cheapest carrier?"

The agent compares rates[*].estimated_cost.amount and narrates the top result.

create_shipment — once the user picks a rate, create the shipment with the chosen carrier_account={ "carrier_id": "<carrier_account_id>" }.
get_carrier_accounts — inspect the carrier accounts that show up in the rate response.

Common chain

Quote and create from natural language — the canonical flow: rate → user picks → create → confirm.

Notes

This tool is more flexible than estimating against an existing shipment id. Always prefer get_shipping_rates when starting from raw order data — pass-through is simpler than create-then-estimate.
Rate calls can be heavy server-side (carrier APIs). Don't loop get_shipping_rates over many shipments for batch quoting unless you've checked rate limits.

get_shipping_rates