Skip to content
Guides
/
/
Rate Shopping
Last updated

Rate Shopping

With the Rates endpoint, you can get shipping rates for multiple carrier and service options. You can then select the desired service for the shipment based on the response or display these at checkout to let your customers choose the fastest, cheapest, or most-trusted service.

There are multiple methods available for getting rates, each with their own use cases:

Additionally, you can get rate estimates with a subset of the information required to create a label.

Requirements

No matter which method you use, you’ll always need the carrier_ids, which will be included in the rate_options object. You can get rates for one or multiple carrier IDs. List carriers to locate your carrier IDs.

There may also be additional requirements, depending on which method you use.

About the /rates/ Endpoint

POST /v2/rates/

  • Given some shipment details and rate options, this endpoint returns a list of rate quotes. You can then use a rate to print a label.
  • You can also choose to validate the address as part of the rate request to help ensure you receive the most-accurate rates possible. There are three address validation options:
    • no_validation: This is the default option and does not validate addresses nor does it confirm the accuracy of an address.
    • validate_only: Validates address accuracy but returns an error if the validation fails.
    • validate_and_clean: Validates address accuracy and updates the address with recommended adjustments.

Example: Find Rates with Shipment Details

Requirements:

  • carrier_ids
  • shipment object

Sample Request

In this example, the shipment details has the no_validation value in the validate_address property.

POST /v2/rates HTTP/1.1
Host: api.shipstation.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json

{
 "rate_options": {
   "carrier_ids": [
     "se-123890"
   ]
 },
 "shipment": {
   "validate_address": "no_validation",
   "ship_to": {
     "name": "The President",
     "phone": "222-333-4444",
     "company_name": "",
     "address_line1": "1600 Pennsylvania Avenue NW",
     "city_locality": "Washington",
     "state_province": "DC",
     "postal_code": "20500",
     "country_code": "US",
     "address_residential_indicator": "no"
   },
   "ship_from": {
     "name": "ShipStation Team",
     "phone": "222-333-4444",
     "company_name": "ShipStation",
     "address_line1": "4301 Bull Creek Road",
     "city_locality": "Austin",
     "state_province": "TX",
     "postal_code": "78731",
     "country_code": "US",
     "address_residential_indicator": "no"
   },
   "packages": [
     {
       "package_code": "package",
       "weight": {
         "value": 6,
         "unit": "ounce"
       }
     }
   ]
 }
}

Example: Find Rates with Shipment ID

If you've already created a shipment, you can pass the shipment_id instead of the full shipment details.

Requirements:

  • carrier_ids
  • shipment_id for a previously created shipment

Sample Request

POST /v2/rates HTTP/1.1
Host: api.shipstation.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json

{
 "shipment_id": "se-123",
 "rate_options": {
   "carrier_ids": [
     "se-123890"
   ]
 }
}

You can pass either the full shipment details or a shipment_id, but you cannot pass both in the same request.

Example: Find Rates with Package Types

Use this method to filter the response by a specific set of package types. If no package type is specified, the default package type for that carrier is used, not all package types.

Requirements:

  • carrier_ids
  • shipment_id or shipment details
  • package_types object and desired values

Sample Request

POST /v2/rates HTTP/1.1
Host: api.shipstation.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json

{
 "shipment_id": "se-123",
 "rate_options": {
   "carrier_ids": [
     "se-123890"
   ],
   "service_codes": [],
   "package_types": [
     "flat_rate_envelope",
     "medium_flat_rate_box"
   ]
 }
}

Example: Find Rates with Service Codes

Use this method to filter the response by a specific set of service codes. If no service code is specified, all service codes are returned.

Requirements:

  • carrier_ids
  • shipment_id or shipment details
  • service_codes object and desired values

Sample Request

POST /v2/rates HTTP/1.1
Host: api.shipstation.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json

{
 "shipment_id": "se-123",
 "rate_options": {
   "carrier_ids": [
     "se-123890"
   ],
   "service_codes": [
     "usps_first_class_mail",
     "usps_priority_mail"
   ],
   "package_types": []
 }
}

Example: Find Rates with Service Codes & Package Types

Use this method to filter the response by a combination of service codes and package types.

Requirements:

  • carrier_ids
  • shipment_id or shipment details
  • package_types object and desired values
  • service_codes object and desired values

Sample Request

POST /v2/rates HTTP/1.1
Host: api.shipstation.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json

{
 "shipment_id": "se-123",
 "rate_options": {
   "carrier_ids": [
     "se-123890"
   ],
   "service_codes": [
     "usps_first_class_mail",
     "usps_priority_mail",
     "ups_next_day_air_early_am"
   ],
   "package_types": [
     "flat_rate_envelope",
     "medium_flat_rate_box"
   ]
 }
}

About the Response

Each rate includes the itemized prices for:

PropertyDescription
shipment_amountCost of shipment only.
insurance_amountCost to insure shipment.
confirmation_amountCost to confirm shipment delivery.
other_amountFees and surcharges from the carrier.

The total rate is the sum of all these amounts.

You may want some additional details about the rates in the response. When it's available, we provide this additional information in the rate_details object.

Here is the structure:

PropertyDescription
rate_detail_typeNormalized type for the additional rate information. These types are enumerated as: uncategorized, shipping, insurance, confirm, discount, fuel_charge, additional_fees, tariff, tax, delivery, handling, special_goods, pickup, location_fee, oversize, returns, notifications, tip, duties_and_taxes, brokerage_fee, admin_fee, adjustment
carrier_descriptionPlain text description of the rate detail as provided by the carrier.
carrier_billing_codeCode for the billing type provided by the carrier.
carrier_memoAdditional text regarding this charge. Usually null.
amountThe currency and amount of the detailed charge.

The rate_details object should match the total of the shipment_amount, insurance_amount, confirmation_amount, and other_amount when it is provided.

Don't want to wait for rates?

We support asynchronous requests using webhooks. However, we recommend waiting if you need to display the rates as a 'next step' for your user or if you're developing for a platform that does not support webhooks.

Sample Response

The response can be lengthy depending on how many carriers you requested rates for. This sample response excludes all but one.

{
   "rate_response": {
       "rates": [
           {
               "rate_id": "se-321654",
               "rate_type": "shipment",
               "carrier_id": "se-123890",
               "shipping_amount": {
                   "currency": "usd",
                   "amount": 10.1
               },
               "insurance_amount": {
                   "currency": "usd",
                   "amount": 0.0
               },
               "confirmation_amount": {
                   "currency": "usd",
                   "amount": 0.0
               },
               "other_amount": {
                   "currency": "usd",
                   "amount": 1.52
               },
               "rate_details": [
                   {
                       "rate_detail_type": "fuel_charge",
                       "carrier_description": "FedEx Ground Fuel",
                       "carrier_billing_code": null,
                       "carrier_memo": null,
                       "amount": {
                           "currency": "usd",
                           "amount": 1.52
                       },
                       "billing_source": "Carrier"
                   },
                   {
                       "rate_detail_type": "shipping",
                       "carrier_description": "Total Net Freight",
                       "carrier_billing_code": null,
                       "carrier_memo": null,
                       "amount": {
                           "currency": "usd",
                           "amount": 10.1
                       },
                       "billing_source": "Carrier"
                   }
               ],
               "zone": 6,
               "package_type": null,
               "delivery_days": 3,
               "guaranteed_service": false,
               "estimated_delivery_date": "2023-04-28T23:59:00Z",
               "carrier_delivery_days": "3",
               "ship_date": "2023-04-25T00:00:00Z",
               "negotiated_rate": false,
               "service_type": "FedEx Ground®",
               "service_code": "fedex_ground",
               "trackable": true,
               "carrier_code": "fedex",
               "carrier_nickname": "My FedEx account",
               "carrier_friendly_name": "FedEx",
               "validation_status": "has_warnings",
               "warning_messages": [
                   "FedEx may add a Home Delivery Surcharge to this shipment later if this is a residential address."
               ],
               "error_messages": []
           }
       ]
       "invalid_rates": [],
       "rate_request_id": "se-987",
       "shipment_id": "se-12345",
       "created_at": "2023-04-25T22:44:33.8102925Z",
       "status": "completed",
       "errors": []
   },
   "shipment_id": "se-12345",
   "carrier_id": "se-123890",
   "service_code": null,
   "external_shipment_id": null,
   "shipment_number": null,
   "ship_date": "2023-04-25T00:00:00Z",
   "created_at": "2023-04-25T22:44:32.887Z",
   "modified_at": "2023-04-25T22:44:32.88Z",
   "shipment_status": "pending",
   "ship_to": {
       "instructions": null,
       "name": "The President",
       "phone": "222-333-4444",
       "company_name": "",
       "address_line1": "1600 Pennsylvania Avenue NW",
       "address_line2": null,
       "address_line3": null,
       "city_locality": "Washington",
       "state_province": "DC",
       "postal_code": "20500",
       "country_code": "US",
       "address_residential_indicator": "no"
   },
   "ship_from": {
       "instructions": null,
       "name": "ShipStation Team",
       "phone": "222-333-4444",
       "company_name": "ShipStation",
       "address_line1": "4301 Bull Creek Road",
       "address_line2": null,
       "address_line3": null,
       "city_locality": "Austin",
       "state_province": "TX",
       "postal_code": "78731",
       "country_code": "US",
       "address_residential_indicator": "no"
   },
   "warehouse_id": null,
   "return_to": {
       "instructions": null,
       "name": "ShipStation Team",
       "phone": "222-333-4444",
       "company_name": "ShipStation",
       "address_line1": "4301 Bull Creek Road",
       "address_line2": null,
       "address_line3": null,
       "city_locality": "Austin",
       "state_province": "TX",
       "postal_code": "78731",
       "country_code": "US",
       "address_residential_indicator": "no"
   },
   "is_return": false,
   "confirmation": "none",
   "customs": {
       "contents": "merchandise",
       "contents_explanation": null,
       "customs_items": [],
       "non_delivery": "return_to_sender",
       "buyer_shipping_amount_paid": null,
       "duties_paid": null,
       "terms_of_trade_code": null,
       "declaration": null,
       "invoice_additional_details": {
           "freight_charge": null,
           "insurance_charge": null,
           "other_charge": null,
           "discount": null
       },
       "importer_of_record": null
   },
   "external_order_id": null,
   "order_source_code": null,
   "advanced_options": {
       "bill_to_account": null,
       "bill_to_country_code": null,
       "bill_to_party": null,
       "bill_to_postal_code": null,
       "contains_alcohol": false,
       "delivered_duty_paid": false,
       "non_machinable": false,
       "saturday_delivery": false,
       "dry_ice": false,
       "dry_ice_weight": null,
       "fedex_freight": null,
       "third_party_consignee": false,
       "ancillary_endorsements_option": null,
       "freight_class": null,
       "custom_field1": null,
       "custom_field2": null,
       "custom_field3": null,
       "collect_on_delivery": null,
       "return_pickup_attempts": null,
       "additional_handling": false
   },
   "insurance_provider": "none",
   "tags": [],
   "packages": [
       {
           "shipment_package_id": "se-65432",
           "package_id": "se-3",
           "package_code": "package",
           "package_name": "Package",
           "weight": {
               "value": 6.00,
               "unit": "ounce"
           },
           "dimensions": {
               "unit": "inch",
               "length": 0.0,
               "width": 0.0,
               "height": 0.0
           },
           "insured_value": {
               "currency": "usd",
               "amount": 0.00
           },
           "label_messages": {
               "reference1": null,
               "reference2": null,
               "reference3": null
           },
           "external_package_id": null,
           "content_description": null,
           "products": []
       }
   ],
   "total_weight": {
       "value": 6.00,
       "unit": "ounce"
   },
   "items": []
}

Rate Estimates

You may find it useful to quickly estimate a rate so you can, for example, add shipping charges to your customer's shopping cart. Estimates work by providing a subset of the information required to create a label using the /v2/rates/estimate endpoint. You can use this method to allow customers to quickly compare rates across services, carriers, and more without having to fill in all the information required to create a label.

Limitations of Rate Estimates

This endpoint does not support multi-package shipments or filtering using the rate_options property. You can filter by carrier adding the desired carrier IDs to the carrier_ids array.

When requesting an estimate, we recommend including the following for the best results:

  • Postal Code To
  • Postal Code From
  • Weight
  • Dimensions (optional, but recommended)

Sample Request

POST /v2/rates/estimate

POST /v2/rates/estimate HTTP/1.1
Host: api.shipstation.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json

{
 "carrier_ids": [
   "se-123890"
 ],
 "from_country_code": "US",
 "from_postal_code": "78756",
 "to_country_code": "US",
 "to_postal_code": "95128",
 "to_city_locality": "San Jose",
 "to_state_province": "CA",
 "weight": {
   "value": 1.0,
   "unit": "ounce"
 },
 "dimensions": {
   "unit": "inch",
   "length": 5.0,
   "width": 5.0,
   "height": 5.0
 },
 "confirmation": "none",
 "address_residential_indicator": "no"
}
Only an Estimate!

Rate estimates are not exact quotes. They do not include things like insurance_amount and may not include other items such as fuel surcharges, customs charges, or other carrier fees.

Automatic Label Creation with Rate Shopper

The Rate Shopper feature takes rate shopping to the next level by automatically selecting and purchasing a label based on your chosen strategy. Instead of manually reviewing rates and selecting one, the Rate Shopper does this for you in a single API call.

How Rate Shopper Works

  1. You provide complete shipment details (addresses, packages, etc.)
  2. You specify a strategy: cheapest, fastest, or best_value
  3. Rate Shopper gets rates from all eligible carriers
  4. Rate Shopper selects the optimal rate based on your strategy
  5. A label is automatically created and returned

Available Strategies

StrategyDescriptionUse Case
cheapestLowest cost optionBest for non-urgent shipments where cost savings are the priority
fastestFastest option at the lowest priceBest for time-sensitive shipments where speed matters most
best_valueLowest cost option arriving within 4 daysBest for shipments where you want reasonable speed without excessive cost

Requirements

  • Wallet carriers connected to your ShipStation API account
  • Complete shipment details (do not include carrier_id, service_code, or shipping_rule_id)
  • Valid rate_shopper_id (cheapest, fastest, or best_value)

Example: Create Label with Rate Shopper

POST /v2/labels/rate_shopper_id/{rate_shopper_id}

This example uses the cheapest strategy to automatically select the lowest-cost carrier and service.

POST /v2/labels/rate_shopper_id/cheapest HTTP/1.1
Host: api.shipstation.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json

{
  "shipment": {
    "ship_to": {
      "name": "Amanda Miller",
      "phone": "555-555-5555",
      "address_line1": "525 S Winchester Blvd",
      "city_locality": "San Jose",
      "state_province": "CA",
      "postal_code": "95128",
      "country_code": "US",
      "address_residential_indicator": "yes"
    },
    "ship_from": {
      "name": "John Doe",
      "company_name": "Example Corp",
      "phone": "111-111-1111",
      "address_line1": "4009 Marathon Blvd",
      "city_locality": "Austin",
      "state_province": "TX",
      "postal_code": "78756",
      "country_code": "US"
    },
    "packages": [{
      "weight": {
        "value": 20,
        "unit": "ounce"
      },
      "dimensions": {
        "height": 6,
        "width": 12,
        "length": 24,
        "unit": "inch"
      }
    }]
  },
  "label_format": "pdf",
  "label_layout": "4x6"
}

Sample Response

The response includes the created label plus information about which rate was selected:

{
  "label_id": "se-396884371",
  "status": "completed",
  "shipment_id": "se-1080108982",
  "ship_date": "2026-02-27T08:00:00Z",
  "created_at": "2026-02-27T17:37:21.648Z",
  "shipment_cost": {
    "currency": "usd",
    "amount": 17.58
  },
  "tracking_number": "1ZYF85760394283643",
  "carrier_id": "se-5904054",
  "service_code": "ups_ground",
  "carrier_code": "ups",
  "rate_shopper_id": "cheapest",
  "label_download": {
    "pdf": "https://api.shipstation.com/v2/downloads/10/xxx/label-396884371.pdf",
    "png": "https://api.shipstation.com/v2/downloads/10/xxx/label-396884371.png",
    "zpl": "https://api.shipstation.com/v2/downloads/10/xxx/label-396884371.zpl",
    "href": "https://api.shipstation.com/v2/downloads/10/xxx/label-396884371.pdf"
  }
}
Rate Shopper vs Manual Rate Shopping

Use Rate Shopper when you want to automate carrier selection in production workflows. Use manual rate shopping (POST /v2/rates) when you need to display rates to customers or review options before purchasing.

Important: Do not include carrier_id, service_code, or shipping_rule_id in your shipment object when using Rate Shopper. The API will return an error if these fields are present, as Rate Shopper automatically determines these values.

Troubleshooting Rate Shopper

No rates available error

If you receive a 404 error, check:

  • You have wallet carriers connected
  • Your shipment parameters are valid
  • The destination is supported by your carriers
  • Package dimensions and weight are within carrier limits

If you need specific carrier selection, use the standard label creation endpoint with explicit carrier_id and service_code.

Previous page
Next page