Skip to content

Get Rates

Request

Retrieve available shipping rates for the given package dimensions, weight, and origin/destination addresses. Returns rates across all active carrier accounts, sorted by price.

Security
BearerAuth or ApiTokenAuth
Bodyapplication/jsonrequired
fromobject(AddressBase)required

Shipper's (origin) address.

toobject(Address)required

Recipient's (destination) address.

shipmentsArray of objects(Parcel)required

One or more parcels to be rated.

orderobject(OrderInfo)
optionsobject(ShippingOptions)
seller_idstring

Caller-defined unique identifier for a merchant or seller. This is an open field — you may pass any value that uniquely identifies a merchant on your platform (e.g., your internal merchant ID). At least one of seller_id or carrier_account_id must be provided. When carrier_account_id is also provided, carrier_account_id takes priority for account matching.

Note: If the seller_id is not associated with a UPS 4th-party account, rate quotes will still be returned, but label purchase will fail.

Example:"merchant_10042"
carrier_account_idstring

Carrier account token in ShipSaving. You can obtain this value from the response of the Create Ghost Account endpoint, or from the ShipSaving system → Carrier Accounts page (the "Token" column in the list). At least one of seller_id or carrier_account_id must be provided. When both are provided, carrier_account_id takes priority.

Note: If the carrier_account_id is not associated with a UPS 4th-party account, rate quotes will still be returned, but label purchase will fail.

Example:"ca_bc28f2e7aaaa4bbbacccbf7d9f2c27xx"
recipient_tax_idsArray of objects(TaxId)

Recipient tax identification numbers for customs.

curl -i -X POST \
  https://ps-api.shipsaving.com/api/rates/list \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "from": {
      "name": "John Doe",
      "company": "Acme Corp",
      "phone": "2135551234",
      "email": "john@example.com",
      "street": "1600 Amphitheatre Parkway",
      "street2": "Suite 200",
      "city": "Mountain View",
      "state": "CA",
      "zip": "94043",
      "country": "US"
    },
    "to": {
      "name": "John Doe",
      "company": "Acme Corp",
      "phone": "2135551234",
      "email": "john@example.com",
      "street": "1600 Amphitheatre Parkway",
      "street2": "Suite 200",
      "city": "Mountain View",
      "state": "CA",
      "zip": "94043",
      "country": "US",
      "residential": false
    },
    "shipments": [
      {
        "length": 12,
        "width": 8,
        "height": 6,
        "weight": 2.5,
        "packages": [
          "usps_small_flat_rate_box"
        ],
        "insurance_amount": 150,
        "custom_print1": "Order #12345",
        "custom_print2": "Fragile",
        "contents": [
          {
            "weight": 0.5,
            "description": "Cotton T-Shirt",
            "quantity": 2,
            "value": 29.99,
            "hs_tariff_number": "610910",
            "origin_country": "US"
          }
        ]
      }
    ],
    "order": {
      "warehouse_name": "WH",
      "store_name": "My Shopify Store",
      "order_number": "20240201125047532",
      "status": "awaiting",
      "service_type": "usps_ground_advantage",
      "signature": "NO_SIGNATURE",
      "insurance_provider": "SHIPSURANCE",
      "contents_type": "MERCHANDISE",
      "non_delivery_option": "RETURN",
      "eel_pfc_type": "ITN",
      "eel_pfc_code": "X20250627012345",
      "tax_ids": [
        {
          "tax_id_type": "IOSS",
          "tax_id_number": "IM1234567890",
          "tax_id_country": "US"
        }
      ]
    },
    "options": {
      "ship_date": "2025-02-07T10:55:56-08:00",
      "require_saturday_delivery": false,
      "require_hazmat": false,
      "hazmat_code": "usps_hazmat_820",
      "label_type": "png",
      "require_qr_code": false
    },
    "seller_id": "merchant_10042",
    "carrier_account_id": "ca_bc28f2e7aaaa4bbbacccbf7d9f2c27xx",
    "recipient_tax_ids": [
      {
        "tax_id_type": "IOSS",
        "tax_id_number": "IM1234567890",
        "tax_id_country": "US"
      }
    ]
  }'

Responses

Rates retrieved successfully

Bodyapplication/json
Array [
shipment_idstring

Shipment identifier for this rate group.

Example:"ship_bea6cc8c-27f8-4dcf-915e-f6aeed8c5600"
rate_idstring

Unique rate identifier. Pass this to Buy Label to purchase.

Example:"rate_e50d02e2-047a-402c-aa32-22ad0926db00"
providerstring

Account provider — shipsaving (discounted) or user (own account).

Example:"shipsaving"
account_namestring

Carrier account display name.

Example:"USPS"
carrierstring

Carrier name (USPS, UPS, FedEx, DHL, etc.).

Example:"USPS"
servicestring

Service level name in uppercase.

Example:"USPS_GROUND_ADVANTAGE"
service_typestring

Service level code in lowercase.

Example:"usps_ground_advantage"
packagestring

Package type name in uppercase.

Example:"PACKAGE"
package_typestring

Package type code in lowercase.

Example:"my_package"
delivery_daysinteger

Estimated transit time in business days.

Example:5
published_ratenumber, (double)

Carrier's retail (list) rate before any discount.

Example:10.9
ratenumber, (double)

Your discounted rate.

Example:8.99
rebatenumber, (double)

Rebate amount credited back after purchase.

Example:0.21
insurance_feenumber, (double)

Insurance fee if insurance was requested.

Example:0
zonestring

Carrier shipping zone.

Example:"4"
is_saturday_deliveryboolean

Whether the rate includes Saturday delivery.

Example:false
]
Response
[
  {
    "shipment_id": "ship_bea6cc8c-27f8-4dcf-915e-f6aeed8c5600",
    "rate_id": "rate_e50d02e2-047a-402c-aa32-22ad0926db00",
    "provider": "shipsaving",
    "account_name": "USPS",
    "carrier": "USPS",
    "service": "USPS_GROUND_ADVANTAGE",
    "service_type": "usps_ground_advantage",
    "package": "PACKAGE",
    "package_type": "my_package",
    "delivery_days": 5,
    "published_rate": 10.9,
    "rate": 8.99,
    "rebate": 0.21,
    "insurance_fee": 0,
    "zone": "4",
    "is_saturday_delivery": false
  }
]