Resources

Rates

Fetch live multi-carrier rates for a parcel. One call returns rates from USPS, UPS, FedEx and DHL with the cheapest highlighted first and a smart-rate category attached for each.

Quote rates

POST/api/v1/labels/quoteScope: write:shipments

Fetches all eligible carrier rates for the given parcel and addresses. Returns up to ~20 rates depending on lane + weight.

Live multi-carrier rate fetch. We hand the parcel + addresses to every carrier with coverage for the lane and stream the results back, sorted ascending by customerPriceCents. Rate fetches do not cost money and are cached for 5 minutes on identical inputs — quoting the same shipment twice in a 5 minute window returns the same rateIds.

Request body

fromAddressobjectrequired
Sender address. See the Addresses page for the full shape.
toAddressobjectrequired
Recipient address. International destinations require non-US country code.
parcelobjectrequired
Dimensions + weight. Required fields: lengthIn, widthIn, heightIn (numbers in inches), weightOz (number in ounces).
serviceCategorystring
Optional filter. One of standard, express, overnight, international. Omit to receive all categories.
customsItemsarray
Required for international shipments. Each item: { description, quantity, valueCents, weightOz, hsCode?, originCountry? }.

Response body

providerShipmentIdstring
Carrier-side shipment handle. Pass it to /labels/create alongside the chosen rateId to skip re-sending addresses.
ratesarray
Rate objects, sorted ascending by customerPriceCents. See below for shape.

Rate object

rateIdstring
Identifier you pass to /labels/create.
carrierstring
USPS / UPS / FedEx / DHL.
servicestring
Carrier-specific service name. Examples: Priority, GroundAdvantage, Ground, FedExGround.
serviceCategorystring
Normalised category — one of standard, express, overnight, international. Filter on this for consistent UX across carriers.
shippingCentsinteger
The shipping portion of the total — everything except the explicit per-label platform fee. Use this if you render a separate 'Shipping' + 'Platform fee' line on your own checkout.
platformFeeCentsinteger
Explicit per-label API fee, $0.08 (8 cents) by default. Broken out so you can itemise it on your own checkout receipts.
customerPriceCentsinteger
Total your account is charged when this rate is bought. Equal to shippingCents + platformFeeCents.
estDeliveryDaysinteger | null
Best-estimate transit time in business days. null when the carrier doesn't return one.
estDeliveryDatestring | null
ISO-8601 date estimate. null when the carrier doesn't return one.

Example

curl -X POST https://shiponline.app/api/v1/labels/quote \
  -H "Authorization: Bearer shp_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "fromAddress": {
      "street1": "123 Main St",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94103",
      "country": "US"
    },
    "toAddress": {
      "street1": "350 Fifth Avenue",
      "city": "New York",
      "state": "NY",
      "zip": "10118",
      "country": "US"
    },
    "parcel": {
      "lengthIn": 10,
      "widthIn": 8,
      "heightIn": 4,
      "weightOz": 16
    },
    "serviceCategory": "standard"
  }'

Sample response (truncated)

JSON

{
  "providerShipmentId": "shp_AAA...",
  "rates": [
    {
      "rateId": "rate_BBB...",
      "carrier": "USPS",
      "service": "Priority",
      "serviceCategory": "express",
      "shippingCents": 820,
      "platformFeeCents": 8,
      "customerPriceCents": 828,
      "estDeliveryDays": 2,
      "estDeliveryDate": "2026-06-29"
    },
    {
      "rateId": "rate_CCC...",
      "carrier": "UPS",
      "service": "Ground",
      "serviceCategory": "standard",
      "shippingCents": 1388,
      "platformFeeCents": 8,
      "customerPriceCents": 1396,
      "estDeliveryDays": 3,
      "estDeliveryDate": "2026-06-30"
    }
  ]
}

Smart-rate categorization

serviceCategorynormalises carrier-specific service names into four buckets so your UI can render consistently. Use it for filtering ("show only overnight options") or sorting your own rate cards ("cheapest within each speed").

standardcategory
Cheapest-but-slowest. USPS Ground Advantage, UPS Ground, FedEx Home Delivery. 2–8 business days.
expresscategory
Mid-tier. USPS Priority Mail, UPS 2-Day, FedEx Express Saver. 1–3 business days.
overnightcategory
Fastest. USPS Priority Mail Express, UPS Next Day Air, FedEx Priority Overnight. Next-day delivery.
internationalcategory
Cross-border. USPS International, UPS Worldwide, FedEx International, DHL Express Worldwide.

International quoting

International rates require a customsItemsarray in the request body. Each item declares what's being shipped for customs declaration purposes — destination customs offices use this to compute duty.

JSON

{
  "fromAddress": { "street1": "...", "city": "...", "state": "CA", "zip": "94103", "country": "US" },
  "toAddress":   { "street1": "...", "city": "Toronto", "state": "ON", "zip": "M5V3L9", "country": "CA" },
  "parcel":      { "lengthIn": 10, "widthIn": 8, "heightIn": 4, "weightOz": 16 },
  "customsItems": [
    {
      "description": "Sterling silver eyeglass frame",
      "quantity": 1,
      "valueCents": 35000,
      "weightOz": 4,
      "hsCode": "9003.19",
      "originCountry": "US"
    }
  ]
}

Cost-routing tip

For international shipments under $200 declared value, DHL Express is rarely the cheapest but is almost always the fastest. USPS International is the cheapest for sub-1lb items going to Western Europe and Canada. Quote all carriers + filter onserviceCategory: international rather than hard- coding a single carrier per destination.

Caching

Identical quote requests (same from/to addresses + parcel + category filter) are cached for 5 minutes client-side. Repeated calls in that window return the same rateId values, so a customer who picks a rate from a cart-page quote can still buy it from the checkout-page quote even if you re-quote between renders.

Outside that window the carriers may return a different price (especially for tiered USPS Priority brackets that change at the weight boundary). Always quote-then-immediately-buy in the same request flow; do not store rateIds overnight.