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.

Note: The SmartRate API is currently available exclusively for US domestic shipments.

Endpoints

GET

/shipments/:id/smartrate

GET

/shipments/:id/smartrate/delivery_date

GET

/shipments/:id/smartrate/precision_shipping

Shipping SmartRate

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 /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": "2025-05-09T20:40:16Z",
7      "currency": "USD",
8      "delivery_date": null,
9      "delivery_date_guaranteed": false,
10      "delivery_days": 2,
11      "est_delivery_days": 2,
12      "id": "rate_2a7a421fb01d45b49d5b6e96d6872c1e",
13      "list_currency": "USD",
14      "list_rate": 51.2,
15      "mode": "test",
16      "object": "Rate",
17      "rate": 51.2,
18      "retail_currency": "USD",
19      "retail_rate": 59.25,
20      "service": "Express",
21      "shipment_id": "shp_270e4e8f5f8b4d9a9b040cefbb8a9694",
22      "time_in_transit": {
23        "percentile_50": 2,
24        "percentile_75": 2,
25        "percentile_85": 3,
26        "percentile_90": 3,
27        "percentile_95": 4,
28        "percentile_97": 5,
29        "percentile_99": 8
30      },
31      "updated_at": "2025-05-09T20:40:16Z"
32    },
33    {
34      "carrier": "USPS",
35      "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac",
36      "created_at": "2025-05-09T20:40:16Z",
37      "currency": "USD",
38      "delivery_date": null,
39      "delivery_date_guaranteed": false,
40      "delivery_days": 2,
41      "est_delivery_days": 2,
42      "id": "rate_da69b97ddd5847dca7cbb2628d7150df",
43      "list_currency": "USD",
44      "list_rate": 11.01,
45      "mode": "test",
46      "object": "Rate",
47      "rate": 11.01,
48      "retail_currency": "USD",
49      "retail_rate": 15.4,
50      "service": "Priority",
51      "shipment_id": "shp_270e4e8f5f8b4d9a9b040cefbb8a9694",
52      "time_in_transit": {
53        "percentile_50": 2,
54        "percentile_75": 2,
55        "percentile_85": 2,
56        "percentile_90": 2,
57        "percentile_95": 3,
58        "percentile_97": 4,
59        "percentile_99": 5
60      },
61      "updated_at": "2025-05-09T20:40:16Z"
62    },
63    {
64      "carrier": "USPS",
65      "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac",
66      "created_at": "2025-05-09T20:40:16Z",
67      "currency": "USD",
68      "delivery_date": null,
69      "delivery_date_guaranteed": false,
70      "delivery_days": 3,
71      "est_delivery_days": 3,
72      "id": "rate_35608b7b51c64bbf93ca16d96ad86d54",
73      "list_currency": "USD",
74      "list_rate": 9.74,
75      "mode": "test",
76      "object": "Rate",
77      "rate": 8.2,
78      "retail_currency": "USD",
79      "retail_rate": 13.85,
80      "service": "GroundAdvantage",
81      "shipment_id": "shp_270e4e8f5f8b4d9a9b040cefbb8a9694",
82      "time_in_transit": {
83        "percentile_50": 1,
84        "percentile_75": 2,
85        "percentile_85": 2,
86        "percentile_90": 2,
87        "percentile_95": 2,
88        "percentile_97": 3,
89        "percentile_99": 5
90      },
91      "updated_at": "2025-05-09T20:40:16Z"
92    }
93  ]
94}

TimeInTransit 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

TimeInTransit Object

{
  "percentile_50": 2,
  "percentile_75": 2,
  "percentile_85": 3,
  "percentile_90": 3,
  "percentile_95": 4,
  "percentile_97": 5,
  "percentile_99": 8
}

Delivery Date

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 /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": 2,
7          "percentile_75": 3,
8          "percentile_85": 3,
9          "percentile_90": 3,
10          "percentile_95": 4,
11          "percentile_97": 5,
12          "percentile_99": 8
13        },
14        "easypost_estimated_delivery_date": "2025-05-14",
15        "planned_ship_date": "2025-05-12"
16      },
17      "rate": {
18        "carrier": "USPS",
19        "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac",
20        "created_at": "2025-05-09T20:40:16Z",
21        "currency": "USD",
22        "delivery_date": null,
23        "delivery_date_guaranteed": false,
24        "delivery_days": 2,
25        "est_delivery_days": 2,
26        "id": "rate_7e023c5a41074bd3bcd039984c361ac0",
27        "list_currency": "USD",
28        "list_rate": 51.2,
29        "mode": "test",
30        "object": "Rate",
31        "rate": 51.2,
32        "retail_currency": "USD",
33        "retail_rate": 59.25,
34        "service": "Express",
35        "shipment_id": "shp_c964ff9f60f2442e9f72ebf038ca599c",
36        "updated_at": "2025-05-09T20:40:16Z"
37      }
38    },
39    {
40      "easypost_time_in_transit_data": {
41        "days_in_transit": {
42          "percentile_50": 3,
43          "percentile_75": 4,
44          "percentile_85": 4,
45          "percentile_90": 5,
46          "percentile_95": 5,
47          "percentile_97": 7,
48          "percentile_99": 8
49        },
50        "easypost_estimated_delivery_date": "2025-05-15",
51        "planned_ship_date": "2025-05-12"
52      },
53      "rate": {
54        "carrier": "USPS",
55        "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac",
56        "created_at": "2025-05-09T20:40:16Z",
57        "currency": "USD",
58        "delivery_date": null,
59        "delivery_date_guaranteed": false,
60        "delivery_days": 2,
61        "est_delivery_days": 2,
62        "id": "rate_3dc348b9c03d421eae1482c4f6c85804",
63        "list_currency": "USD",
64        "list_rate": 11.01,
65        "mode": "test",
66        "object": "Rate",
67        "rate": 11.01,
68        "retail_currency": "USD",
69        "retail_rate": 15.4,
70        "service": "Priority",
71        "shipment_id": "shp_c964ff9f60f2442e9f72ebf038ca599c",
72        "updated_at": "2025-05-09T20:40:16Z"
73      }
74    },
75    {
76      "easypost_time_in_transit_data": {
77        "days_in_transit": {
78          "percentile_50": 3,
79          "percentile_75": 4,
80          "percentile_85": 4,
81          "percentile_90": 5,
82          "percentile_95": 5,
83          "percentile_97": 7,
84          "percentile_99": 8
85        },
86        "easypost_estimated_delivery_date": "2025-05-15",
87        "planned_ship_date": "2025-05-12"
88      },
89      "rate": {
90        "carrier": "USPS",
91        "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac",
92        "created_at": "2025-05-09T20:40:16Z",
93        "currency": "USD",
94        "delivery_date": null,
95        "delivery_date_guaranteed": false,
96        "delivery_days": 3,
97        "est_delivery_days": 3,
98        "id": "rate_1463dbc3ec7e4508a90c4b68f19dd2f2",
99        "list_currency": "USD",
100        "list_rate": 9.74,
101        "mode": "test",
102        "object": "Rate",
103        "rate": 8.2,
104        "retail_currency": "USD",
105        "retail_rate": 13.85,
106        "service": "GroundAdvantage",
107        "shipment_id": "shp_c964ff9f60f2442e9f72ebf038ca599c",
108        "updated_at": "2025-05-09T20:40:16Z"
109      }
110    }
111  ]
112}

Precision Shipping

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

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": 3,
7          "percentile_75": 3,
8          "percentile_85": 4,
9          "percentile_90": 4,
10          "percentile_95": 5,
11          "percentile_97": 6,
12          "percentile_99": 7
13        },
14        "delivery_date_confidence": 0.72,
15        "desired_delivery_date": "2025-05-19",
16        "estimated_transit_days": 3,
17        "ship_on_date": "2025-05-16"
18      },
19      "rate": {
20        "carrier": "USPS",
21        "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac",
22        "created_at": "2025-05-12T19:26:15Z",
23        "currency": "USD",
24        "delivery_date": null,
25        "delivery_date_guaranteed": false,
26        "delivery_days": 2,
27        "est_delivery_days": 2,
28        "id": "rate_9e7a3960ed5648c4a2cd294b304da3fa",
29        "list_currency": "USD",
30        "list_rate": 11.01,
31        "mode": "test",
32        "object": "Rate",
33        "rate": 11.01,
34        "retail_currency": "USD",
35        "retail_rate": 15.4,
36        "service": "Priority",
37        "shipment_id": "shp_e736bad8b71142feabe22f6602a6b301",
38        "updated_at": "2025-05-12T19:26:15Z"
39      }
40    },
41    {
42      "easypost_time_in_transit_data": {
43        "days_in_transit": {
44          "percentile_50": 3,
45          "percentile_75": 4,
46          "percentile_85": 4,
47          "percentile_90": 4,
48          "percentile_95": 5,
49          "percentile_97": 6,
50          "percentile_99": 8
51        },
52        "delivery_date_confidence": 0.68,
53        "desired_delivery_date": "2025-05-19",
54        "estimated_transit_days": 3,
55        "ship_on_date": "2025-05-16"
56      },
57      "rate": {
58        "carrier": "USPS",
59        "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac",
60        "created_at": "2025-05-12T19:26:15Z",
61        "currency": "USD",
62        "delivery_date": null,
63        "delivery_date_guaranteed": false,
64        "delivery_days": 3,
65        "est_delivery_days": 3,
66        "id": "rate_c7d63ed32fef4c4f82332fabe40ee4f0",
67        "list_currency": "USD",
68        "list_rate": 9.74,
69        "mode": "test",
70        "object": "Rate",
71        "rate": 8.2,
72        "retail_currency": "USD",
73        "retail_rate": 13.85,
74        "service": "GroundAdvantage",
75        "shipment_id": "shp_e736bad8b71142feabe22f6602a6b301",
76        "updated_at": "2025-05-12T19:26:15Z"
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": 6,
88          "percentile_99": 10
89        },
90        "delivery_date_confidence": 0.54,
91        "desired_delivery_date": "2025-05-19",
92        "estimated_transit_days": 2,
93        "ship_on_date": "2025-05-17"
94      },
95      "rate": {
96        "carrier": "USPS",
97        "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac",
98        "created_at": "2025-05-12T19:26:15Z",
99        "currency": "USD",
100        "delivery_date": null,
101        "delivery_date_guaranteed": false,
102        "delivery_days": 2,
103        "est_delivery_days": 2,
104        "id": "rate_c07c76156ed943c5b1906cdbd2f368b3",
105        "list_currency": "USD",
106        "list_rate": 51.2,
107        "mode": "test",
108        "object": "Rate",
109        "rate": 51.2,
110        "retail_currency": "USD",
111        "retail_rate": 59.25,
112        "service": "Express",
113        "shipment_id": "shp_e736bad8b71142feabe22f6602a6b301",
114        "updated_at": "2025-05-12T19:26:15Z"
115      }
116    }
117  ]
118}