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

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 we need to know some basic information to get a rate.

Below are four ways to POST calls in JSON, the response returns you should see, 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
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": "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"
},
"packages": [
{
"weight": {
"value": 1.0,
"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
{
"rate_response": {
"rate_request_id": 501834,
"shipment_id": "se-2127183",
"status": "completed",
"created_at": "2019-07-26T22:10:50.286Z",
"rates": [
{
"rate_id": "se-11744390",
"rate_type": "shipment",
"carrier_id": "se-123890",
"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": "2019-07-26T05:00:00.000Z",
"carrier_delivery_days": "Friday by 11:00 PM",
"ship_date": "2019-07-26T05:00:00.000Z",
"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": "2019-07-26T05:00:00.000Z",
"created_at": "2019-07-26T22:10:50.286Z",
"modified_at": "2019-07-26T22:10:50.286Z",
"shipment_status": "pending",
"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"
},
"return_to": {
"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",
"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
}
}
]
}

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.

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

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