Api ReferenceRates API

Compare Carrier Rates In One Request

Shop eligible USPS and UPS services with a single authenticated POST. Use the same ZIP-to-ZIP contract as the SyncShip Rate Browser.

Get API key Read API reference

Overview

The Rates API returns comparable quotes for a package between two postal codes. Responses include carrier, service, amount, and optional delivery estimates so you can present options or auto-select the cheapest eligible rate.

POST /api/v1/shipments/rates
Filter by carrier, service, or delivery speed
Residential and commercial surcharges included
Response time depends on request type and downstream carrier services

Authentication

Authenticate every request with a Bearer token issued for your SyncShip developer account.

http

Authorization: Bearer YOUR_API_KEY

Endpoint

Send a JSON body describing origin, destination, and package details. The service returns the set of available rates for enabled carriers on your account.

POST/api/v1/shipments/rates

bash

curl -X POST https://api.sync-ship.com/api/v1/shipments/rates \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "fromPostalCode": "10001", "toPostalCode": "90210", "toCountry": "US", "residential": true, "weightLb": 2, "weightOz": 0, "length": 12, "width": 8, "height": 4, "packageType": "package", "carriers": ["usps", "ups"]}'

Request

Required fields cover origin ZIP, destination ZIP, and weight. Dimensions and carrier filters are optional but improve quote accuracy.

Parameter	Type	Required	Description
fromPostalCode	string	Yes	Origin postal code (ship-from).
toPostalCode	string	Yes	Destination postal code (ship-to).
toCountry	string	No	ISO destination country. Defaults to US when omitted.
residential	boolean	No	Whether the destination is residential. Affects surcharges.
weightLb	number	Yes	Package weight in pounds.
weightOz	number	Yes	Additional ounces beyond whole pounds.
length	number	No	Package length in inches.
width	number	No	Package width in inches.
height	number	No	Package height in inches.
packageType	string	No	Carrier package type when applicable (for example package).
carriers	string[]	No	Limit quotes to enabled SyncShip carriers such as usps or ups.

json

{
  "fromPostalCode": "10001",
  "toPostalCode": "90210",
  "toCountry": "US",
  "residential": true,
  "weightLb": 2,
  "weightOz": 0,
  "length": 12,
  "width": 8,
  "height": 4,
  "packageType": "package",
  "carriers": ["usps", "ups"]
}

Response

Successful responses include a source indicator, carrier coverage counts, and an array of rate objects. Amounts are returned in the account currency.

Example response

json

{
  "source": "usps",
  "carriersAvailable": 2,
  "carriersTotal": 2,
  "rates": [
    {
      "carrier": "usps",
      "serviceCode": "priority",
      "serviceName": "Priority Mail",
      "deliveryDays": "1-3",
      "amount": 9.85,
      "currency": "USD"
    },
    {
      "carrier": "ups",
      "serviceCode": "ground",
      "serviceName": "UPS Ground",
      "deliveryDays": "1-5",
      "amount": 12.4,
      "currency": "USD"
    }
  ]
}

Errors

Standard HTTP status codes are used. Treat 4xx as client corrections and retry 429 with backoff.

401Missing or invalid API key.
422Validation failed — check postal codes, weight, or dimensions.
429Too many requests — retry with exponential backoff.

Next steps

After you can shop rates, continue with label purchase, event delivery, or the sandbox quickstart.

Labels API Webhooks Quickstart

Bring Every Order Into One Queue

Start free