Shipping SmartRate
The Shipping SmartRate API provides shippers with highly accurate, shipment-level transit time predictions that can save money, improve on-time delivery, and provide end customers with reliable delivery estimates.
The /smartrate endpoint accepts a Shipment ID and
returns a time_in_transit object that
includes transit business days across various percentiles for every Rate associated with a given
Shipment. Transit business days are calculated as the number of business days
(Monday-Friday) from when the carrier first acknowledges possession of the shipment to the initial out-for-delivery
attempt.
Create a Shipment. Based on the shipping schedule or delivery
requirements, choose the appropriate SmartRate endpoint and call it by passing the shipment_id. Use the response to
select the most appropriate rate for the shipment.
GET /
1curl -X GET https://api.easypost.com/v2/shipments/shp_.../smartrate \
2 -u "EASYPOST_API_KEY":Response
1{
2 "result": [
3 {
4 "carrier": "USPS",
5 "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac",
6 "created_at": "2024-01-24T00:07:44Z",
7 "currency": "USD",
8 "delivery_date": null,
9 "delivery_date_guaranteed": false,
10 "delivery_days": null,
11 "est_delivery_days": null,
12 "id": "rate_29120e36c58a4232b14547e53b0131c6",
13 "list_currency": "USD",
14 "list_rate": 49.6,
15 "mode": "test",
16 "object": "Rate",
17 "rate": 49.6,
18 "retail_currency": "USD",
19 "retail_rate": 57.4,
20 "service": "Express",
21 "shipment_id": "shp_91721066728d473999b736a0d3f88ce8",
22 "time_in_transit": {
23 "percentile_50": 1,
24 "percentile_75": 2,
25 "percentile_85": 2,
26 "percentile_90": 3,
27 "percentile_95": 3,
28 "percentile_97": 4,
29 "percentile_99": 6
30 },
31 "updated_at": "2024-01-24T00:07:44Z"
32 },
33 {
34 "carrier": "USPS",
35 "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac",
36 "created_at": "2024-01-24T00:07:44Z",
37 "currency": "USD",
38 "delivery_date": null,
39 "delivery_date_guaranteed": false,
40 "delivery_days": 2,
41 "est_delivery_days": 2,
42 "id": "rate_ea6e4920d07142f694e8d81a89fe3cd1",
43 "list_currency": "USD",
44 "list_rate": 10.89,
45 "mode": "test",
46 "object": "Rate",
47 "rate": 7.33,
48 "retail_currency": "USD",
49 "retail_rate": 15.2,
50 "service": "Priority",
51 "shipment_id": "shp_91721066728d473999b736a0d3f88ce8",
52 "time_in_transit": {
53 "percentile_50": 1,
54 "percentile_75": 2,
55 "percentile_85": 2,
56 "percentile_90": 2,
57 "percentile_95": 3,
58 "percentile_97": 3,
59 "percentile_99": 3
60 },
61 "updated_at": "2024-01-24T00:07:44Z"
62 },
63 {
64 "carrier": "USPS",
65 "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac",
66 "created_at": "2024-01-24T00:07:44Z",
67 "currency": "USD",
68 "delivery_date": null,
69 "delivery_date_guaranteed": false,
70 "delivery_days": 3,
71 "est_delivery_days": 3,
72 "id": "rate_26cb7b0f451e407db3adddb432a38b19",
73 "list_currency": "USD",
74 "list_rate": 9.41,
75 "mode": "test",
76 "object": "Rate",
77 "rate": 6.79,
78 "retail_currency": "USD",
79 "retail_rate": 13.15,
80 "service": "GroundAdvantage",
81 "shipment_id": "shp_91721066728d473999b736a0d3f88ce8",
82 "time_in_transit": {
83 "percentile_50": 1,
84 "percentile_75": 2,
85 "percentile_85": 2,
86 "percentile_90": 2,
87 "percentile_95": 3,
88 "percentile_97": 3,
89 "percentile_99": 4
90 },
91 "updated_at": "2024-01-24T00:07:44Z"
92 },
93 {
94 "carrier": "USPS",
95 "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac",
96 "created_at": "2024-01-24T00:07:44Z",
97 "currency": "USD",
98 "delivery_date": null,
99 "delivery_date_guaranteed": false,
100 "delivery_days": 3,
101 "est_delivery_days": 3,
102 "id": "rate_3e9facc8738d41ecb3ff17b9c75d6669",
103 "list_currency": "USD",
104 "list_rate": 9.41,
105 "mode": "test",
106 "object": "Rate",
107 "rate": 6.79,
108 "retail_currency": "USD",
109 "retail_rate": 13.15,
110 "service": "First",
111 "shipment_id": "shp_91721066728d473999b736a0d3f88ce8",
112 "time_in_transit": {
113 "percentile_50": 1,
114 "percentile_75": 2,
115 "percentile_85": 2,
116 "percentile_90": 2,
117 "percentile_95": 3,
118 "percentile_97": 3,
119 "percentile_99": 4
120 },
121 "updated_at": "2024-01-24T00:07:44Z"
122 },
123 {
124 "carrier": "USPS",
125 "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac",
126 "created_at": "2024-01-24T00:07:44Z",
127 "currency": "USD",
128 "delivery_date": null,
129 "delivery_date_guaranteed": false,
130 "delivery_days": 3,
131 "est_delivery_days": 3,
132 "id": "rate_c40cd28b908141649d8b66c4189266e0",
133 "list_currency": "USD",
134 "list_rate": 9.41,
135 "mode": "test",
136 "object": "Rate",
137 "rate": 6.79,
138 "retail_currency": "USD",
139 "retail_rate": 13.15,
140 "service": "ParcelSelect",
141 "shipment_id": "shp_91721066728d473999b736a0d3f88ce8",
142 "time_in_transit": {
143 "percentile_50": 1,
144 "percentile_75": 2,
145 "percentile_85": 2,
146 "percentile_90": 2,
147 "percentile_95": 3,
148 "percentile_97": 3,
149 "percentile_99": 4
150 },
151 "updated_at": "2024-01-24T00:07:44Z"
152 }
153 ]
154}percentile_50
integer
Expected transit days at the 50th percentile
percentile_75
integer
Expected transit days at the 75th percentile
percentile_85
integer
Expected transit days at the 85th percentile
percentile_90
integer
Expected transit days at the 90th percentile
percentile_95
integer
Expected transit days at the 95th percentile
percentile_97
integer
Expected transit days at the 97th percentile
percentile_99
integer
Expected transit days at the 99th percentile
Time in Transit Object
{
"percentile_50": 1,
"percentile_75": 2,
"percentile_85": 2,
"percentile_90": 3,
"percentile_95": 3,
"percentile_97": 4,
"percentile_99": 6
}The /delivery_date endpoint provides estimated delivery dates for shipments, helping users identify cost-effective service levels and enhance delivery timeliness.
Call the /delivery_date endpoint by passing the shipment_id and the date the shipment will enter the mailstream using the planned_ship_date attribute. Review the returned easypost_time_in_transit_data object.
GET /
1curl -X GET https://api.easypost.com/v2/shipments/shp_.../smartrate/delivery_date?planned_ship_date=yyyy-mm-dd \
2 -u "EASYPOST_API_KEY":Response
1{
2 "rates": [
3 {
4 "easypost_time_in_transit_data": {
5 "days_in_transit": {
6 "percentile_50": 3,
7 "percentile_75": 3,
8 "percentile_85": 6,
9 "percentile_90": 6,
10 "percentile_95": 6,
11 "percentile_97": 6,
12 "percentile_99": 9
13 },
14 "easypost_estimated_delivery_date": "2024-01-26",
15 "planned_ship_date": "2024-01-24"
16 },
17 "rate": {
18 "carrier": "USPS",
19 "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac",
20 "created_at": "2024-01-24T00:07:45Z",
21 "currency": "USD",
22 "delivery_date": null,
23 "delivery_date_guaranteed": false,
24 "delivery_days": 3,
25 "est_delivery_days": 3,
26 "id": "rate_36a64db214ab4fafaeaaad6855ebf422",
27 "list_currency": "USD",
28 "list_rate": 9.41,
29 "mode": "test",
30 "object": "Rate",
31 "rate": 6.79,
32 "retail_currency": "USD",
33 "retail_rate": 13.15,
34 "service": "GroundAdvantage",
35 "shipment_id": "shp_e3ce96ba8b6745608fe1c419d76b8fb5",
36 "updated_at": "2024-01-24T00:07:45Z"
37 }
38 },
39 {
40 "easypost_time_in_transit_data": {
41 "days_in_transit": {
42 "percentile_50": 3,
43 "percentile_75": 3,
44 "percentile_85": 6,
45 "percentile_90": 6,
46 "percentile_95": 6,
47 "percentile_97": 6,
48 "percentile_99": 9
49 },
50 "easypost_estimated_delivery_date": "2024-01-26",
51 "planned_ship_date": "2024-01-24"
52 },
53 "rate": {
54 "carrier": "USPS",
55 "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac",
56 "created_at": "2024-01-24T00:07:45Z",
57 "currency": "USD",
58 "delivery_date": null,
59 "delivery_date_guaranteed": false,
60 "delivery_days": 3,
61 "est_delivery_days": 3,
62 "id": "rate_90170bc6328b46cda598d683828d6ac6",
63 "list_currency": "USD",
64 "list_rate": 9.41,
65 "mode": "test",
66 "object": "Rate",
67 "rate": 6.79,
68 "retail_currency": "USD",
69 "retail_rate": 13.15,
70 "service": "First",
71 "shipment_id": "shp_e3ce96ba8b6745608fe1c419d76b8fb5",
72 "updated_at": "2024-01-24T00:07:45Z"
73 }
74 },
75 {
76 "easypost_time_in_transit_data": {
77 "days_in_transit": {
78 "percentile_50": 3,
79 "percentile_75": 3,
80 "percentile_85": 6,
81 "percentile_90": 6,
82 "percentile_95": 6,
83 "percentile_97": 6,
84 "percentile_99": 9
85 },
86 "easypost_estimated_delivery_date": "2024-01-26",
87 "planned_ship_date": "2024-01-24"
88 },
89 "rate": {
90 "carrier": "USPS",
91 "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac",
92 "created_at": "2024-01-24T00:07:45Z",
93 "currency": "USD",
94 "delivery_date": null,
95 "delivery_date_guaranteed": false,
96 "delivery_days": 3,
97 "est_delivery_days": 3,
98 "id": "rate_ca519ed1f83d4a8ebc5c17a1dbe96553",
99 "list_currency": "USD",
100 "list_rate": 9.41,
101 "mode": "test",
102 "object": "Rate",
103 "rate": 6.79,
104 "retail_currency": "USD",
105 "retail_rate": 13.15,
106 "service": "ParcelSelect",
107 "shipment_id": "shp_e3ce96ba8b6745608fe1c419d76b8fb5",
108 "updated_at": "2024-01-24T00:07:45Z"
109 }
110 },
111 {
112 "easypost_time_in_transit_data": {
113 "days_in_transit": {
114 "percentile_50": 1,
115 "percentile_75": 2,
116 "percentile_85": 2,
117 "percentile_90": 3,
118 "percentile_95": 3,
119 "percentile_97": 6,
120 "percentile_99": 7
121 },
122 "easypost_estimated_delivery_date": "2024-01-25",
123 "planned_ship_date": "2024-01-24"
124 },
125 "rate": {
126 "carrier": "USPS",
127 "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac",
128 "created_at": "2024-01-24T00:07:45Z",
129 "currency": "USD",
130 "delivery_date": null,
131 "delivery_date_guaranteed": false,
132 "delivery_days": null,
133 "est_delivery_days": null,
134 "id": "rate_30c5c922506445a88b51212c52ac2db3",
135 "list_currency": "USD",
136 "list_rate": 49.6,
137 "mode": "test",
138 "object": "Rate",
139 "rate": 49.6,
140 "retail_currency": "USD",
141 "retail_rate": 57.4,
142 "service": "Express",
143 "shipment_id": "shp_e3ce96ba8b6745608fe1c419d76b8fb5",
144 "updated_at": "2024-01-24T00:07:45Z"
145 }
146 },
147 {
148 "easypost_time_in_transit_data": {
149 "days_in_transit": {
150 "percentile_50": 2,
151 "percentile_75": 3,
152 "percentile_85": 3,
153 "percentile_90": 6,
154 "percentile_95": 6,
155 "percentile_97": 6,
156 "percentile_99": 8
157 },
158 "easypost_estimated_delivery_date": "2024-01-26",
159 "planned_ship_date": "2024-01-24"
160 },
161 "rate": {
162 "carrier": "USPS",
163 "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac",
164 "created_at": "2024-01-24T00:07:45Z",
165 "currency": "USD",
166 "delivery_date": null,
167 "delivery_date_guaranteed": false,
168 "delivery_days": 2,
169 "est_delivery_days": 2,
170 "id": "rate_4d9a5348efb44acbb25d162e1a692cb0",
171 "list_currency": "USD",
172 "list_rate": 10.89,
173 "mode": "test",
174 "object": "Rate",
175 "rate": 7.33,
176 "retail_currency": "USD",
177 "retail_rate": 15.2,
178 "service": "Priority",
179 "shipment_id": "shp_e3ce96ba8b6745608fe1c419d76b8fb5",
180 "updated_at": "2024-01-24T00:07:45Z"
181 }
182 }
183 ]
184}The /precision_shipping endpoint of the SmartRate API enhances shipping accuracy by allowing shippers to specify a desired delivery date. The API then suggests the best ship date for each carrier and service level to meet this delivery date. In addition to the suggested ship_on_date, a delivery_date_confidence score is provided, indicating the likelihood of delivery on the desired date.
Call the /precision_shipping endpoint by passing the shipment_id into the API request along with the desired_delivery_date. Utilize the returned data to plan shipments precisely.
This endpoint requires the desired_delivery_date parameter to generate highly accurate predictions.
Request Parameters
shipment_id
REQUIRED
i.e. "10001"
Unique, begins with "shp_"
from_zip
REQUIRED
i.e. "10001"
Specifies the postal code from which the shipment will originate.
GET /
1curl -X GET https://api.easypost.com/v2/shipments/shp_.../smartrate/precision_shipping?desired_delivery_date=yyyy-mm-dd \
2 -u "EASYPOST_API_KEY":Response
1{
2 "rates": [
3 {
4 "easypost_time_in_transit_data": {
5 "days_in_transit": {
6 "percentile_50": 2,
7 "percentile_75": 3,
8 "percentile_85": 4,
9 "percentile_90": 4,
10 "percentile_95": 5,
11 "percentile_97": 5,
12 "percentile_99": 7
13 },
14 "delivery_date_confidence": 0.19,
15 "desired_delivery_date": "2024-07-16",
16 "estimated_transit_days": 3,
17 "ship_on_date": "2024-07-13"
18 },
19 "rate": {
20 "carrier": "USPS",
21 "carrier_account_id": "ca_716f33fd9fd348238b85c2922237f98b",
22 "created_at": "2024-07-11T18:55:42Z",
23 "currency": "USD",
24 "delivery_date": null,
25 "delivery_date_guaranteed": false,
26 "delivery_days": 2,
27 "est_delivery_days": 2,
28 "id": "rate_bdfda26163de43878a65e0f456b30ddb",
29 "list_currency": "USD",
30 "list_rate": 8.25,
31 "mode": "test",
32 "object": "Rate",
33 "rate": 6.9,
34 "retail_currency": "USD",
35 "retail_rate": 9.8,
36 "service": "Priority",
37 "shipment_id": "shp_3d7216c496144494acf875f0a9555272",
38 "updated_at": "2024-07-11T18:55:42Z"
39 }
40 },
41 {
42 "easypost_time_in_transit_data": {
43 "days_in_transit": {
44 "percentile_50": 2,
45 "percentile_75": 3,
46 "percentile_85": 4,
47 "percentile_90": 4,
48 "percentile_95": 5,
49 "percentile_97": 5,
50 "percentile_99": 9
51 },
52 "delivery_date_confidence": 0.21,
53 "desired_delivery_date": "2024-07-16",
54 "estimated_transit_days": 3,
55 "ship_on_date": "2024-07-13"
56 },
57 "rate": {
58 "carrier": "USPS",
59 "carrier_account_id": "ca_716f33fd9fd348238b85c2922237f98b",
60 "created_at": "2024-07-11T18:55:42Z",
61 "currency": "USD",
62 "delivery_date": null,
63 "delivery_date_guaranteed": false,
64 "delivery_days": 3,
65 "est_delivery_days": 3,
66 "id": "rate_475a7a2b833e401abe78bb26e3fda731",
67 "list_currency": "USD",
68 "list_rate": 6.4,
69 "mode": "test",
70 "object": "Rate",
71 "rate": 5.93,
72 "retail_currency": "USD",
73 "retail_rate": 8.45,
74 "service": "GroundAdvantage",
75 "shipment_id": "shp_3d7216c496144494acf875f0a9555272",
76 "updated_at": "2024-07-11T18:55:42Z"
77 }
78 },
79 {
80 "easypost_time_in_transit_data": {
81 "days_in_transit": {
82 "percentile_50": 2,
83 "percentile_75": 3,
84 "percentile_85": 4,
85 "percentile_90": 4,
86 "percentile_95": 5,
87 "percentile_97": 5,
88 "percentile_99": 9
89 },
90 "delivery_date_confidence": 0.21,
91 "desired_delivery_date": "2024-07-16",
92 "estimated_transit_days": 3,
93 "ship_on_date": "2024-07-13"
94 },
95 "rate": {
96 "carrier": "USPS",
97 "carrier_account_id": "ca_716f33fd9fd348238b85c2922237f98b",
98 "created_at": "2024-07-11T18:55:42Z",
99 "currency": "USD",
100 "delivery_date": null,
101 "delivery_date_guaranteed": false,
102 "delivery_days": 3,
103 "est_delivery_days": 3,
104 "id": "rate_253b47e9de5f4159ab4d1509adaf83cb",
105 "list_currency": "USD",
106 "list_rate": 6.4,
107 "mode": "test",
108 "object": "Rate",
109 "rate": 5.93,
110 "retail_currency": "USD",
111 "retail_rate": 8.45,
112 "service": "First",
113 "shipment_id": "shp_3d7216c496144494acf875f0a9555272",
114 "updated_at": "2024-07-11T18:55:42Z"
115 }
116 },
117 {
118 "easypost_time_in_transit_data": {
119 "days_in_transit": {
120 "percentile_50": 2,
121 "percentile_75": 3,
122 "percentile_85": 4,
123 "percentile_90": 4,
124 "percentile_95": 5,
125 "percentile_97": 5,
126 "percentile_99": 9
127 },
128 "delivery_date_confidence": 0.21,
129 "desired_delivery_date": "2024-07-16",
130 "estimated_transit_days": 3,
131 "ship_on_date": "2024-07-13"
132 },
133 "rate": {
134 "carrier": "USPS",
135 "carrier_account_id": "ca_716f33fd9fd348238b85c2922237f98b",
136 "created_at": "2024-07-11T18:55:42Z",
137 "currency": "USD",
138 "delivery_date": null,
139 "delivery_date_guaranteed": false,
140 "delivery_days": 3,
141 "est_delivery_days": 3,
142 "id": "rate_565d5a7580f54504af994b65f969ac1b",
143 "list_currency": "USD",
144 "list_rate": 6.4,
145 "mode": "test",
146 "object": "Rate",
147 "rate": 5.93,
148 "retail_currency": "USD",
149 "retail_rate": 8.45,
150 "service": "ParcelSelect",
151 "shipment_id": "shp_3d7216c496144494acf875f0a9555272",
152 "updated_at": "2024-07-11T18:55:42Z"
153 }
154 },
155 {
156 "easypost_time_in_transit_data": {
157 "days_in_transit": {
158 "percentile_50": 2,
159 "percentile_75": 2,
160 "percentile_85": 2,
161 "percentile_90": 3,
162 "percentile_95": 3,
163 "percentile_97": 4,
164 "percentile_99": 7
165 },
166 "delivery_date_confidence": 0.47,
167 "desired_delivery_date": "2024-07-16",
168 "estimated_transit_days": 1,
169 "ship_on_date": "2024-07-15"
170 },
171 "rate": {
172 "carrier": "USPS",
173 "carrier_account_id": "ca_716f33fd9fd348238b85c2922237f98b",
174 "created_at": "2024-07-11T18:55:42Z",
175 "currency": "USD",
176 "delivery_date": null,
177 "delivery_date_guaranteed": false,
178 "delivery_days": 2,
179 "est_delivery_days": 2,
180 "id": "rate_33de2fbd3f5340eebebb47338723a631",
181 "list_currency": "USD",
182 "list_rate": 33.1,
183 "mode": "test",
184 "object": "Rate",
185 "rate": 33.1,
186 "retail_currency": "USD",
187 "retail_rate": 37.9,
188 "service": "Express",
189 "shipment_id": "shp_3d7216c496144494acf875f0a9555272",
190 "updated_at": "2024-07-11T18:55:42Z"
191 }
192 }
193 ]
194}