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:
- Find rates with
shipmentdetails - Find rates with
shipment_id - Find Rates with Package Types
- Find Rates with Service Codes
- Find Rates with both Service Codes and Package Types
Additionally, you can get rates for multiple shipments and 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_idsshipmentobject
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_idsshipment_idfor 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_idsshipment_idorshipmentdetailspackage_typesobject 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_idsshipment_idorshipmentdetailsservice_codesobject 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_idsshipment_idorshipmentdetailspackage_typesobject and desired valuesservice_codesobject 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:
| 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.
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.
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 Multiple Shipments
You can request rates for shipments in bulk using the /v2/rates/bulk endpoint. If you subscribe to webhooks, you will receive a notification when the operation is complete. You can then retrieve the rates and create a label using the rate_id.
Sample Request
POST /v2/rates/bulk
In this sample, we request rates for shipments that were previously created by passing the desired shipment IDs in the shipment_ids array.
POST /v2/rates/bulk HTTP/1.1 Host: api.shipstation.com API-Key: __YOUR_API_KEY_HERE__ Content-Type: application/json { "shipment_ids": [ "se-2127226", "se-2127227" ], "rate_options": { "carrier_ids": [ "se-123890", "se-121861" ] } }
Alternatively, you can include the shipment object in the rate request rather than referencing an existing shipment. In this case, a shipment will be created for you and include a shipment_id with each rate.
POST /v2/rates/bulk HTTP/1.1 Host: api.shipstatione.com API-Key: __YOUR_API_KEY_HERE__ Content-Type: application/json { "rate_options": { "carrier_ids": [ "se-123890", "se-123890" ] }, "shipments": [{ "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": { "company_name": "Example Corp.", "name": "John Doe", "phone": "111-111-1111", "address_line1": "4009 Marathon Blvd", "address_line2": "Suite 300", "city_locality": "Austin", "state_province": "TX", "postal_code": "78756", "country_code": "US", "address_residential_indicator": "no" }, "confirmation": "none", "packages": [{ "package_code": "package", "weight": { "value": 12, "unit": "ounce" } }] }, { "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": { "company_name": "Example Corp.", "name": "John Doe", "phone": "111-111-1111", "address_line1": "4009 Marathon Blvd", "address_line2": "Suite 300", "city_locality": "Austin", "state_province": "TX", "postal_code": "78756", "country_code": "US", "address_residential_indicator": "no" }, "confirmation": "none", "packages": [{ "package_code": "package", "weight": { "value": 1, "unit": "pound" } }] }, { "ship_to": { "name": "Waffle HQ", "company_name": "Waffle House", "address_line1": "5986 Financial Drive", "address_line2": null, "address_line3": null, "city_locality": "Norcross", "state_province": "GA", "postal_code": "30071", "country_code": "US", "phone": "111-111-1111" }, "ship_from": { "company_name": "Example Corp.", "name": "John Doe", "phone": "111-111-1111", "address_line1": "4009 Marathon Blvd", "address_line2": "Suite 300", "city_locality": "Austin", "state_province": "TX", "postal_code": "78756", "country_code": "US", "address_residential_indicator": "no" }, "confirmation": "none", "packages": [{ "package_code": "package", "weight": { "value": 1, "unit": "ounce" } }] }, { "ship_to": { "name": "Jony Ive", "company_name": "Apple", "address_line1": "1 Infinite Loop", "address_line2": null, "address_line3": null, "city_locality": "Cupertino", "state_province": "CA", "postal_code": "95014", "country_code": "US", "phone": "408-996-1010" }, "ship_from": { "company_name": "Example Corp.", "name": "John Doe", "phone": "111-111-1111", "address_line1": "4009 Marathon Blvd", "address_line2": "Suite 300", "city_locality": "Austin", "state_province": "TX", "postal_code": "78756", "country_code": "US", "address_residential_indicator": "no" }, "confirmation": "none", "packages": [{ "package_code": "package", "weight": { "value": 1, "unit": "ounce" } }] }, { "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": { "company_name": "Example Corp.", "name": "John Doe", "phone": "111-111-1111", "address_line1": "4009 Marathon Blvd", "address_line2": "Suite 300", "city_locality": "Austin", "state_province": "TX", "postal_code": "78756", "country_code": "US", "address_residential_indicator": "no" }, "confirmation": "none", "packages": [{ "package_code": "package", "weight": { "value": 1, "unit": "ounce" } }] } ] }
Sample Response
Due to the length of the response, we have truncated this sample to only show a single rate. When you run this command, you will notice many more rates returned in the response.
[ { "rate_request_id": 501846, "shipment_id": "se-2127226", "status": "working", "created_at": "2019-07-25T15:24:46.657Z" }, { "rate_request_id": 501847, "shipment_id": "se-2127227", "status": "working", "created_at": "2019-07-25T15:24:46.657Z" } ]
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.
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" }
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.