Advanced Rating Features

ShipEngine's Rate Shopping feature has many facets, and can provide additonal utility above getting the quoted cost for a shipment. In this article we'll review some features that ShipEngine offers to help make the most of your shipping integration.

Retail Rates

By default, ShipEngine will return the same rate that you'd see if you signed into your carrier account on their website and tried to ship a package. There are plenty of usecases where it can be valuable to see the rate available if a user were to go to the carrier's retail location and purchase postage. This feature allows those rates to be visible from ShipEngine.

Some things to note:

If ShipEngine does not support retail rates for the carrier you are querying, we will return a 0 amount.
The response object requested_comparison_amount is a sum of the carrier costs for the shipment. It should be compared against the sum of shipping_amount, confirmation_amount and other_amount (insurance_amount will only be a factor if you choose carrier insurance).
This feature is only available at the /v1/rates and /v1/labels endpoints when creating rates or labels with a shipment.

Example Retail Rates Request

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
{
    "shipment": {
        "comparison_rate_type": "retail",
        "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"
                }
            }
        ]
    },
    "rate_options": {
        "carrier_ids": [
            "se-12345"
        ]
    }
}

You can also pass the comparison_rate_type in the shipment when creating a label!

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
{
    "rate_response": {
        "rates": [
            {
                "rate_id": "se-6384266",
                "rate_type": "shipment",
                "carrier_id": "se-204152",
                "shipping_amount": {
                    "currency": "usd",
                    "amount": 6.7300
                },
                "insurance_amount": {
                    "currency": "usd",
                    "amount": 0.0
                },
                "confirmation_amount": {
                    "currency": "usd",
                    "amount": 0.0
                },
                "other_amount": {
                    "currency": "usd",
                    "amount": 0.0
                },
                "requested_comparison_amount": {
                    "currency": "usd",
                    "amount": 9.3500
                },
                "rate_details": [],
                "zone": 1,
                "package_type": "package",
                "delivery_days": 1,
                "guaranteed_service": false,
                "estimated_delivery_date": "2023-11-02T00:00:00Z",
                "carrier_delivery_days": "1",
                "ship_date": "2023-11-01T00:00:00Z",
                "negotiated_rate": false,
                "service_type": "USPS Priority Mail",
                "service_code": "usps_priority_mail",
                "trackable": true,
                "carrier_code": "usps",
                "carrier_nickname": "My Stamps account",
                "carrier_friendly_name": "USPS",
                "validation_status": "valid",
                "warning_messages": [],
                "error_messages": []
            }
        ],
        "invalid_rates": [],
        "rate_request_id": "se-12345",
        "shipment_id": "se-12345",
        "created_at": "2023-11-01T15:53:03.8069761Z",
        "status": "completed",
        "errors": []
    },
    "shipment_id": "se-12345",
    "carrier_id": null,
    "service_code": null,
    "external_shipment_id": null,
    "shipment_number": null,
    "ship_date": "2023-11-01T00:00:00Z",
    "created_at": "2023-11-01T15:52:52.833Z",
    "modified_at": "2023-11-01T15:52:52.773Z",
    "shipment_status": "pending",
    "ship_to": {
        "instructions": null,
        "name": "Bruce Wayne",
        "phone": "222-333-4444",
        "email": null,
        "company_name": "Wayne Enterprises",
        "address_line1": "1990 E. Grand Ave",
        "address_line2": null,
        "address_line3": null,
        "city_locality": "El Segundo",
        "state_province": "CA",
        "postal_code": "90245",
        "country_code": "US",
        "address_residential_indicator": "no"
    },
    "ship_from": {
        "instructions": null,
        "name": "Bruce Wayne",
        "phone": "222-333-4444",
        "email": null,
        "company_name": "Wayne Enterprises",
        "address_line1": "1990 E. Grand Ave",
        "address_line2": null,
        "address_line3": null,
        "city_locality": "El Segundo",
        "state_province": "CA",
        "postal_code": "90245",
        "country_code": "US",
        "address_residential_indicator": "no"
    },
    "warehouse_id": null,
    "return_to": {
        "instructions": null,
        "name": "Bruce Wayne",
        "phone": "222-333-4444",
        "email": null,
        "company_name": "Wayne Enterprises",
        "address_line1": "1990 E. Grand Ave",
        "address_line2": null,
        "address_line3": null,
        "city_locality": "El Segundo",
        "state_province": "CA",
        "postal_code": "90245",
        "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,
            "other_charge_description": 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,
        "own_document_upload": false,
        "limited_quantity": false
    },
    "comparison_rate_type": null,
    "insurance_provider": "none",
    "tags": [],
    "packages": [
        {
            "shipment_package_id": "se-12345",
            "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": []}

Quick Rates

We've found that when getting rates just in time to purchase a label, milliseconds matter. That's why we've developed a way to combine the speed of the Rate Estimate endpoint and the detail of the Rates endpoint to offer you a fast and fully-featured way to retrieve rates.

Quick Rates saves time by minimizing the information ShipEngine saves about your request. That means you won't be able to use operations like Create Label from Rate or Retrieve Shipment Rates. You will, however, be able to rate international and multi-package shipments with advanced options. You can even use Quick Rates with Retail Rates!

Example Quick Rates Request

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": {
        "rate_type": "quick",
        "carrier_ids": [
            "se-12345"
        ]
    },
    "shipment": {
        "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"
                }
            }
        ]
    }
}

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
{
    "rate_response": {
        "rates": [
            {
                "rate_id": null,
                "rate_type": "quick",
                "carrier_id": "se-204152",
                "shipping_amount": {
                    "currency": "usd",
                    "amount": 8.4100
                },
                "insurance_amount": {
                    "currency": "usd",
                    "amount": 0.0
                },
                "confirmation_amount": {
                    "currency": "usd",
                    "amount": 0.0
                },
                "other_amount": {
                    "currency": "usd",
                    "amount": 0.0
                },
                "requested_comparison_amount": {
                    "currency": "usd",
                    "amount": 0.0
                },
                "rate_details": [],
                "zone": 6,
                "package_type": "package",
                "delivery_days": 2,
                "guaranteed_service": false,
                "estimated_delivery_date": "2023-11-03T00:00:00Z",
                "carrier_delivery_days": "2",
                "ship_date": "2023-11-01T00:00:00Z",
                "negotiated_rate": false,
                "service_type": "USPS Priority Mail",
                "service_code": "usps_priority_mail",
                "trackable": true,
                "carrier_code": "usps",
                "carrier_nickname": "My Stamps account",
                "carrier_friendly_name": "USPS",
                "validation_status": "valid",
                "warning_messages": [],
                "error_messages": []
            }
        ],
        "invalid_rates": [],
        "created_at": "2023-11-01T10:38:32.4333382Z",
        "status": "completed",
        "errors": []
    }
}