Docs
Sign in

Shipping rates

Updated July 31, 20262 min read

Use shipping rates to compare the cost of shipping across your carrier accounts and choose which carrier handles a shipment. The endpoint takes a shipment-shaped payload and a set of carrier accounts to price, and returns one rate per eligible carrier account: cost, currency, service descriptor, and (when available) an estimated transit time.

For example, a merchant with two FedEx services (FedEx Economy 2–3 Day and FedEx Priority Overnight) can set up each as its own carrier account and rate-shop both, then book on whichever the operator or an automation rule selects.

The rate-shop runs on the internal POST /carrier-accounts/shipping-rates endpoint — it operates on carrier accounts, not on the shopper-facing storefront. For shopper-facing pricing, present Delivery options instead: a curated, named list ("Standard", "Express", "Click and Collect") priced for the customer.

Multiple carrier accounts per carrier

A merchant can configure several carrier accounts for the same carrier, each pointing at a different service. That's how you rate-shop multiple service levels for the same carrier as separate options. Each account is independent: its own configuration, its own rate source, its own eligibility.

Where the rate comes from

Each carrier account is configured with one of two rate sources:

  • Carrier Shipping Rates. Carriyo fetches the rate from the carrier's rates API in real time. Most accurate, but the rate API takes a moment and depends on the carrier being reachable.
  • Costing profile. Carriyo computes the rate from a costing profile the merchant has configured on the carrier account (fixed cost, weight tiers, surcharges, etc.). Fast and deterministic.

The choice is per carrier account. A typical merchant uses a mix: large carriers via their rate APIs (accurate, worth the latency), smaller or regional carriers via costing profiles (fast, predictable).

What the response carries

For each priced carrier account, the response includes the carrier account identifier, the carrier, the service descriptor, the computed cost and currency. When the rate source provides it, an estimated transit time is included as well.

When an account is excluded (inactive, network coverage gap, weight cap exceeded, or rate-API failure), the response reports the reason. This lets you diagnose unexpected absences.

The bridge to booking

Once a carrier service is chosen, persist the selected carrier_account_id on the shipment. When the shipment is booked, pass that id in and Carriyo books on the chosen account. The rate that was quoted is the rate that gets honored.

How it fits with other modules

  • Carrier configuration. The parent page — carrier accounts, costing profiles, and the Carrier Shipping Rates toggle are configured here.
  • Delivery options. The shopper-facing alternative for presenting priced delivery choices at checkout.
  • Booking flow. How a chosen carrier account becomes a booked shipment.