Get Shipping Rates

Learn how to get the rates of all carriers and services you have connected to ShipEngine®!

Requirements

  • Getting rates assumes you understand how to List Your Carriers.
  • Getting rates requires that you use a carrier_id.

It's not uncommon that you want to give your customer the choice between whether they want to ship the fastest, cheapest, or the most trusted route. Most companies don't solely ship things using a single shipping option; so we provide functionality to show you all your options!

Similar to the Quickstart: Create a Label we need to know some basic information to get a rate.

/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 choose to validate the address as part of the rate request, which will help ensure that you get back the most accurate rates possible. The address validations options are:

Validation Option
Description

no_validation

Do not utilize address validation, to confirm the accuracy of the address

validate_only

Validate the accuracy of the address, and provide an updated address with recommended adjustments

validate_and_clean

Validate the accuracy of the address, and update the address with recommended adjustments.

Example (with shipment details)

This example shows how to get rates by passing-in the shipment details and rate options.

curl '$apiUrl$/v1/rates' -X POST \
  -H "Content-type: application/json" \
  -H $apiAuth$ \
  -d '
{
  "shipment": {
    "validate_address": "no_validation",
    "ship_to": {
      "name": "Mickey and Minnie Mouse",
      "phone": "714-781-4565",
      "company_name": "The Walt Disney Company",
      "address_line1": "500 South Buena Vista Street",
      "city_locality": "Burbank",
      "state_province": "CA",
      "postal_code": "91521",
      "country_code": "US"
    },
    "ship_from": {
      "name": "Dade Murphy",
      "phone": "512-485-4282",
      "company_name": "Zero Cool",
      "address_line1": "345 Chambers Street",
      "address_line2": "Suite 100",
      "city_locality": "New York City",
      "state_province": "NY",
      "postal_code": "10282",
      "country_code": "US",
    },
    "packages": [
      {
        "weight": {
          "value": 1.0,
          "unit": "ounce"
        }
      }
    ]
  },
  "rate_options": {
    "carrier_ids": [
      "#stampsId#"
    ]
  }
}'

Example (with shipment_id)

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

Note

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

curl '$apiUrl$/v1/rates' -X POST \
  -H "Content-type: application/json" \
  -H $apiAuth$ \
  -d '
{
  "shipment_id": "se-123",
  "rate_options": {
    "carrier_ids": [
      "#stampsId#"
    ]
  }
}'

The response can be quite daunting depending on how many carriers you requested rates from. We excluded all but one in our response below. As you can see, there's a lot of data that comes back in a response.

Pro Tip

Each rate includes itemized prices for shipment_amount, insurance_amount, confirmation_amount, and other_amount. The total rate is the sum of all these amounts.

{
  "rate_response": {
    "rate_request_id": 501834,
    "shipment_id": "se-2127183",
    "status": "completed",
    "created_at": "$date$",
    "rates": [
      {
        "rate_id": "se-11744390",
        "rate_type": "shipment",
        "carrier_id": "$upsId$",
        "shipping_amount": {
          "currency": "usd",
          "amount": 9.37
        },
        "insurance_amount": {
          "currency": "usd",
          "amount": 0.00
        },
        "confirmation_amount": {
          "currency": "usd",
          "amount": 0.00
        },
        "other_amount": {
          "currency": "usd",
          "amount": 0.00
        },
        "delivery_days": 3,
        "guaranteed_service": false,
        "estimated_delivery_date": "$shipDate$",
        "carrier_delivery_days": "Friday by 11:00 PM",
        "ship_date": "$shipDate$",
        "negotiated_rate": false,
        "service_type": "UPS® Ground",
        "service_code": "ups_ground",
        "trackable": true,
        "validation_status": "valid",
        "warning_messages": [],
        "error_messages": [],
        "carrier_code": "ups",
        "carrier_nickname": "UPS-28A1R9",
        "carrier_friendly_name": "UPS"
      }
    ],
    "invalid_rates": []
  },
  "shipment_id": "se-2127183",
  "carrier_id": "",
  "external_shipment_id": null,
  "ship_date": "$shipDate$",
  "created_at": "$date$",
  "modified_at": "$date$",
  "shipment_status": "pending",
  "ship_to": {
    "name": "Mickey and Minnie Mouse",
    "phone": "714-781-4565",
    "company_name": "The Walt Disney Company",
    "address_line1": "500 S BUENA VISTA ST",
    "address_line2": "",
    "city_locality": "BURBANK",
    "state_province": "CA",
    "postal_code": "91521-0001",
    "country_code": "US",
    "address_residential_indicator": "no"
  },
  "ship_from": {
    "name": "Dade Murphy",
    "phone": "212-555-5555",
    "company_name": "Zero Cool",
    "address_line1": "345 Chambers Street",
    "address_line2": "Suite 100",
    "city_locality": "New York City",
    "state_province": "NY",
    "postal_code": "10282",
    "country_code": "US",
    "address_residential_indicator": "unknown"
  },
  "return_to": {
    "name": "Dade Murphy",
    "phone": "212-555-5555",
    "company_name": "Zero Cool Returns",
    "address_line1": "345 Chambers Street",
    "address_line2": "Suite 100",
    "city_locality": "New York City",
    "state_province": "NY",
    "postal_code": "10282",
    "country_code": "US",
    "address_residential_indicator": "unknown"
  },
  "confirmation": "none",
  "advanced_options": {
    "bill_to_account": null,
    "bill_to_country_code": null,
    "bill_to_party": null,
    "bill_to_postal_code": null,
    "contains_alcohol": false,
    "custom_field1": null,
    "custom_field2": null,
    "custom_field3": null,
    "non_machinable": false,
    "saturday_delivery": false
  },
  "insurance_provider": "none",
  "tags": [],
  "total_weight": {
    "value": 1.00,
    "unit": "ounce"
  },
  "packages": [
    {
      "weight": {
        "value": 1.00,
        "unit": "ounce"
      },
      "dimensions": {
        "unit": "inch",
        "length": 0.0,
        "width": 0.0,
        "height": 0.0
      },
      "insured_value": {
        "currency": "usd",
        "amount": 0.0
      }
    }
  ]
}

Don't want to wait for rates?

ShipEngine supports asynchronous requests using Web Hooks and status polling.

Waiting is recommended 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 web hooks.