Shipping rate API: how real-time rates work

A shipping rate API returns live carrier prices for a specific shipment: you send the origin, destination, and package details, and it responds with a list of available services and their costs in real time. That live pricing is what lets a checkout show accurate shipping charges instead of a flat guess, and it is what powers automated rate shopping in the warehouse. This guide walks through how real-time rating works, what data you must send to get an accurate quote, and how to handle the response cleanly.

It is part of our hub on shipping APIs for developers. If you are new to the topic, start with what is a shipping API for the big picture.

How a real-time shipping rate API works

Real-time rating means the price you show comes from the carrier's current rate tables, not a cached estimate. When your code calls the rate endpoint, the API forwards the shipment details to each eligible carrier (or evaluates them against negotiated rate cards), collects the quotes, and returns them together. The whole round trip usually takes a fraction of a second to a couple of seconds.

Here is the shape of a typical rate request. This is generic illustrative pseudo-REST to show the pattern, not the exact Expership contract; the real endpoint and field names are in the Expership API reference at /developers.

POST /rates
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "from": { "postal_code": "33101", "country": "US" },
  "to":   { "postal_code": "98101", "country": "US" },
  "parcel": {
    "weight_oz": 48,
    "length_in": 14,
    "width_in": 10,
    "height_in": 6
  }
}

And the response, a list of priced services you can rank, filter, or display:

{
  "rates": [
    { "carrier": "CarrierA", "service": "Ground",       "amount": 9.85,  "est_days": 4 },
    { "carrier": "CarrierA", "service": "2-Day",         "amount": 18.40, "est_days": 2 },
    { "carrier": "CarrierB", "service": "Priority",      "amount": 12.15, "est_days": 3 }
  ]
}

Field names vary by provider, so confirm the exact response shape in the docs at /developers before you map it.

What data you must send for an accurate quote

A rate is only as accurate as the inputs. Four things drive the price, and getting any of them wrong means the quote will not match the carrier's invoice later.

• Origin and destination - at minimum postal code and country. Residential versus commercial delivery can also change the price, so pass it if you know it.
• Weight - the actual scale weight of the packed parcel.
• Dimensions - length, width, and height of the box. Carriers price on billable weight, which is the greater of actual weight and dimensional weight. Skip dimensions and your quotes will be too low on bulky, light items.
• Service level or filters - optionally restrict to certain carriers or speeds so you only get back options you can actually use.

The single most common cause of a quote that does not match the invoice is a package size that is smaller in your API call than the box you actually shipped. Measure the packed parcel, not the product.

Rate shopping: picking the best option automatically

Because the API returns every eligible service at once, you can compare them programmatically and let code choose. This is rate shopping, and it is one of the highest-leverage things a rate API enables. A simple rule might be: pick the cheapest service that still delivers by the promised date.

// Given the rates array from the response
const maxDays = 3;
const eligible = rates.filter(r => r.est_days <= maxDays);
const best = eligible.sort((a, b) => a.amount - b.amount)[0];
// best is the cheapest option that meets the delivery window

Done consistently across every shipment, rate shopping is one of the most reliable ways to reduce shipping costs without changing anything a customer sees.

Where to use rate quotes

Performance and reliability tips

Rating sits on the critical path for checkout, so treat it like any latency-sensitive dependency:

• Set a timeout and a fallback. If the rate call is slow or fails, fall back to a sensible flat rate or cached estimate so checkout never hangs.
• Cache selectively. Rates for identical shipments can be cached for a short window, but do not cache so long that a rate change surprises you.
• Validate the address first. A bad postal code produces a bad or failed quote. An address validation API upstream keeps rating clean.
• Handle partial failures. If one carrier times out, still show the quotes that did come back rather than failing the whole request.

Getting started with Expership

Expership provides a multi-carrier shipping API that includes real-time rating for ecommerce sellers and consolidators shipping into the U.S. Explore the reference at /developers, see the broader platform, or create an account to get sandbox keys and pull your first quote. For the wider context of where rating fits, see what is shipping software and multi-carrier shipping explained.

Frequently asked questions

What is a shipping rate API?

It is an endpoint that takes a shipment's origin, destination, weight, and dimensions and returns live carrier prices for the available services. It is what lets an app quote real shipping cost instead of a flat estimate.

Why do my API rates not match the carrier's invoice?

Almost always because the package details you sent were wrong, most often the dimensions. Carriers bill on dimensional weight, so an understated box size produces an understated quote. Send the true packed size and weight.

How fast is a real-time rate call?

Typically well under two seconds. Because it is on the checkout path, always set a timeout and a fallback so a slow carrier response cannot stall the buyer.

Can I get rates from multiple carriers in one call?

Yes. That is the point of a multi-carrier rate API: a single request returns quotes from every eligible carrier, which you can then compare and rate shop automatically.

Do I need dimensions to get a rate?

You can often get a rough quote from weight alone, but for an accurate price you must send dimensions. Carriers price on billable weight, the greater of actual and dimensional weight, so bulky light items will be underquoted without them.