Looking for the old docs? View our old docs site.
API Docs

SmartRate

The SmartRate API provides shippers with highly accurate, shipment-level transit time predictions which can be used to save money, improve on-time delivery, and provide end customers with reliable delivery estimates.

The SmartRate API accepts a Shipment ID and returns predicted transit days across a variety of percentiles for each carrier service being evaluated for the Shipment. The transit time predictions in the response are based off of a sophisticated model using actual historical data for the shipping lane in question.

To make a request to the SmartRate API, first create a Shipment, then make the SmartRate call. Using the response, you can now make better data-driven decisions about which Rate to select when purchasing a label.

Endpoints
GET
/shipments/:id/smartrate
GET
/shipments/:id/smartrate/delivery_date

Time in Transit object

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
}

Retrieve Time in Transit statistics across all Rates for a Shipment

The SmartRate API returns a TimeInTransit object with transit days across a variety of percentiles for every

Rate for a given Shipment. Transit days are calculated as the number of business days between the first time the carrier acknowledges possession of the Shipment and the first out-for-delivery attempt.

GET /shipments/:id/smartrate
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}

Retrieve Estimated Delivery Date and Total Transit Days across all Rates for a Shipment

The Delivery Date endpoint of the SmartRate API will return an EasyPost Estimated Delivery Date as well as a DaysInTransit object that contains the expected number of total days the shipment is to be in transit across a variety of percentiles for every Rate for a given

Shipment. Transit days are calculated as the number of days (including weekends and holidays) between the first time the carrier acknowledges possession of the Shipment and the first out-for-delivery attempt.

This endpoint requires the parameter planned_ship_date to be provided when called. This is the date that the user would expect the carrier to take possession of the shipment. Knowing this makes the results of the API extremely accurate.

GET /shipments/:id/smartrate/delivery_date
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}