Calculate Shipping Costs

With the ShipEngine 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 ShipEngine, make sure you have the following first:

An active ShipEngine account. You can sign up here if you haven't already.
Your ShipEngine 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": "ShipEngine Team",
      "phone": "222-333-4444",
      "company_name": "ShipEngine",
      "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"
    ]
  }
}

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

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.

Sample Response

The response can be lengthy depending on how many carriers you requested rates for. This sample response excludes all but one.

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
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
{
    "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": "ShipEngine Team",
        "phone": "222-333-4444",
        "company_name": "ShipEngine",
        "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": "ShipEngine Team",
        "phone": "222-333-4444",
        "company_name": "ShipEngine",
        "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": []
}