Site Logo

Calculate Shipping Costs

ShipEngine is a REST API that allows you to manage almost every facet possible for shipping. This tutorial will show you how to create a rate.

Before you begin:

This article helps you to make a POST call to get shipping rates for your multiple carrier and service options.

Display these at checkout to let your customers choose the fastest, cheapest, or most-trusted route when you ship your products.

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

Below are four examples of different ways to POST calls in JSON. Each example includes the response you should see returned, and how to understand and use their results. These examples include:

Examples

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.

Choose to validate the address as part of the rate request to help ensure that you get back the most-accurate rates possible. There are three address validation options:

Validation OptionDescription
no_validationThis default option in ShipEngine does not validate addresses nor does it confirm the accuracy of an address.
validate_onlyValidates address accuracy but returns an error if the validation fails.
validate_and_cleanValidates address accuracy and updates the address with recommended adjustments.

Example Requests

This JSON example passes shipment details and no_validation for the validate_address property in the POST call.

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"
}
}
]
}
}

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

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"
]
}
}

Example Response

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.

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
{
"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
}
},
{
"rate_detail_type": "shipping",
"carrier_description": "Total Net Freight",
"carrier_billing_code": null,
"carrier_memo": null,
"amount": {
"currency": "usd",
"amount": 10.1
}
}
],
"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": []
}

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.

You may want some additional detail about the rates coming back. When it's avaialable, we provide this additional information in the rate_details object. This is structured:

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

Example: Find Rates with Package Types

This example shows how to get rates that are filtered by a specific set of package types. If no package type is specified the the default package type for that carrier is used, not all package types.

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"
]
}
}

Example (Find Rates with service codes)

This example shows how to get rates that are filtered by a specific set of service codes. If no service code is specified then all service codes are returned.

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": []
}
}

Example (Find Rates with service codes and package types)

This example shows how to get rates that are filtered by a combination of service codes and package types.

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"
]
}
}