Calculate Shipping Costs

With the ShipStation API 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.

If you are new to ShipStation API, make sure you have the following first:

An active ShipStation API account. You can sign up here if you haven't already.
Your ShipStation API key (a sandbox API key will work for the steps provided below).
A tool to make an API call, like curl or Postman.

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

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 /v1/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.

Find Rates Using Shipment Details

Requirements:

carrier_ids
shipment object

Sample Request

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
POST /v1/rates HTTP/1.1
Host: api.shipengine.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 API Team",
      "phone": "222-333-4444",
      "company_name": "ShipStation API corp.",
      "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"
        }
      }
    ]
  }
}

Find Rates Using Shipment ID

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

Requirements:

carrier_ids
shipment_id for a previously created shipment.

Sample Request

1
2
3
4
5
6
7
8
9
10
11
12
13
POST /v1/rates HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json
{
  "shipment_id": "se-123",
  "rate_options": {
    "carrier_ids": [
      "se-123890"
    ]
  }
}

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

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
POST /v1/rates HTTP/1.1
Host: api.shipengine.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"
    ]
  }
}

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
POST /v1/rates HTTP/1.1
Host: api.shipengine.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": []
  }
}

Find Rates with Service Codes and Package Types

Use this method to filter the resonse 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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
POST /v1/rates HTTP/1.1
Host: api.shipengine.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

The response returns a list of rates from your connected carriers along with related shipment data. For domestic U.S. shipments, the first three rates typically include a rate_attributes object that highlights the best value, cheapest, and fastest options for quick comparison. The rates are then sorted from cheapest to most expensive.

When you make this call, a shipment object is automatically created with a shipment_id, allowing you to update it and retrieve new rates before purchasing a label.

To explore optional functionality, see the advanced rating features guide.

Rate Attributes

A single rate may have multiple attributes applied however each attribute only exists once in the response. The following table defines the possible rate attributes and their meanings:

Rate Attribute	Description
`best_value`	Lowest cost option arriving on a specified date within 4 days, with free carrier coverage up to $100 and a free dropoff option.
`cheapest`	Lowest cost option
`fastest`	Fastest delivery option

Itemized Rate Breakdown

Each rate includes the itemized prices for:

Property	Description
`shipment_amount`	Cost of shipment only.
`insurance_amount`	Cost to insure shipment.
`confirmation_amount`	Cost to confirm shipment delivery.
`other_amount`	Fees and surcharges from the carrier.

The total rate is the sum of all these amounts.

Rate Details Object

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:

Property	Description
`rate_detail_type`	Normalized 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_description`	Plain text description of the rate detail as provided by the carrier.
`carrier_billing_code`	Code for the billing type provided by the carrier.
`carrier_memo`	Additional text regarding this charge. Usually null.
`amount`	The `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.

TIP:

Don't want to wait for rates?

ShipStation API supports 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": [],
                "rate_attributes": [
                    "best_value",
                    "fastest",
                    "cheapest"
                ]
            }
        ]
        "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 API Team",
        "phone": "222-333-4444",
        "company_name": "ShipStation API corp.",
        "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 API Team",
        "phone": "222-333-4444",
        "company_name": "ShipStation API corp.",
        "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": []
}

Automatic Label Creation with Rate Shopper

Once you understand how rate shopping works, you might want to automate the entire process. The Rate Shopper feature eliminates the need to manually review rates and select one — it automatically chooses and purchases a label based on your strategy in a single API call.

How It Works

Instead of making two separate calls (one for rates, another for label creation), Rate Shopper:

Gets rates from all your wallet carriers
Selects the optimal rate based on your chosen strategy
Purchases the label automatically
Returns the completed label with details about which carrier and service were selected

When to Use Rate Shopper

Scenario	Recommended Approach
Automated fulfillment workflows where you want consistent, hands-off carrier selection	✅ Use Rate Shopper
Displaying rates to customers at checkout for them to choose	❌ Use manual rate shopping (`POST /v1/rates`)
Reviewing options before committing to a carrier	❌ Use manual rate shopping (`POST /v1/rates`)
High-volume shipping with clear cost or speed priorities	✅ Use Rate Shopper

Available Strategies

The rate_shopper_id determines which carrier and service will be selected:

cheapest: Best for non-urgent shipments where cost savings are the priority
fastest: Best for time-sensitive shipments where speed matters most
best_value: Best for balancing reasonable speed (within 4 days) without excessive cost

Learn more: See Create a Label with Rate Shopper for implementation details and examples.