Skip to content
Guides/
/
Calculate Shipping Rates
Last updated

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:

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

  1. Find rates with shipment details
  2. Find rates with shipment_id
  3. Find Rates with Package Types
  4. Find Rates with Service Codes
  5. Find Rates with both Service Codes and Package Types

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.

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

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

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

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

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 AttributeDescription
best_valueLowest cost option arriving on a specified date within 4 days, with free carrier coverage up to $100 and a free dropoff option.
cheapestLowest cost option
fastestFastest delivery option

Itemized Rate Breakdown

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.

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:

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.

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:

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

When to Use Rate Shopper

ScenarioRecommended 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.

Previous page
Next page
Shipstation
  • Facebook
  • Linkedin
  • Instagram
Auctane
ShipStation is powered by Auctane, a global delivery experience company. © 2026 Auctane, Inc. All rights reserved