Docs
Sign in

Shipping rates

Updated May 29, 20262 min read

Use shipping rates when you want to expose carrier services directly to the customer at checkout. The endpoint takes a shipment-shaped payload 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 present both at checkout. The customer picks which service they want to pay for.

For a curated, named list of options instead ("Standard", "Express", "Click and Collect"), use Delivery options.

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 expose multiple service levels for the same carrier as separate choices at checkout. 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 eligible 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

When the customer picks a carrier service at checkout, persist the chosen carrier_account_id on the order. When the shipment is created, pass that id in and Carriyo books on the chosen account. The rate the customer saw is the rate that gets honored.

How it fits with other modules