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_idsshipmentobject
Sample Request
In this example, the shipment details uses the no_validation value in the validate_address property.
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_idsshipment_idfor a previously created shipment.
Sample 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_idsshipment_idorshipmentdetailspackage_typesobject and desired values
Sample Request
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_idsshipment_idorshipmentdetailsservice_codesobject and desired values
Sample Request
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_idsshipment_idorshipmentdetailspackage_typesobject and desired valuesservice_codesobject and desired values
Sample Request
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.
Sample Response
The response can be lengthy depending on how many carriers you requested rates for. This sample response excludes all but one.
