API Docs

SmartRate

The Smart Deliver By and Smart Deliver On endpoints are designed for precise delivery scheduling scenarios. The Smart Deliver By endpoint specifies a delivery deadline, while the Smart Deliver On endpoint enables setting a specific delivery date.

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

Endpoints
POST
/smartrate/deliver_by
POST
/smartrate/deliver_on

SmartRate Object

planned_ship_date
datetime
Date the shipment is expected to enter the mailstream.
easypost_estimated_delivery_date
datetime
Estimated delivery date for the shipment in YYYY/MM/DD format, including weekends and holidays.
desired_delivery_date
datetime
Target delivery date for the package. Failure to provide this date results in a failed API call.
days_in_transit
integer
Estimated transit times at various percentiles. These transit times include holidays and weekends.
delivery_date_confidence
integer
Indicates the likelihood (0-1 scale) of a package being delivered on the specified delivery date.
estimated_transit_days
integer
Total number of days expected for the package to be delivered on the desired delivery date, assuming it is shipped on the suggested ship_on_date.
ship_on_date
datetime
Recommended date for dispatching the package to the carrier to ensure delivery by the desired delivery date.
from_zip
string
Specifies the postal code from which the shipment will originate.
to_zip
string
Specifies the postal code to which the shipment is destined.
SmartRate Object
{
  "carriers_without_tint_estimates": null,
  "desired_delivery_date": "2025-05-19",
  "from_zip": "10001",
  "results": [
    {
      "carrier": "usps",
      "easypost_time_in_transit_data": {
        "days_in_transit": {
          "percentile_50": 2,
          "percentile_75": 2,
          "percentile_85": 3,
          "percentile_90": 3,
          "percentile_95": 4,
          "percentile_97": 5,
          "percentile_99": 8
        },
        "delivery_date_confidence": 0.68,
        "estimated_transit_days": 2,
        "ship_on_date": "2025-05-17"
      },
      "service": "express"
    },
    {
      "carrier": "usps",
      "easypost_time_in_transit_data": {
        "days_in_transit": {
          "percentile_50": 2,
          "percentile_75": 2,
          "percentile_85": 3,
          "percentile_90": 3,
          "percentile_95": 4,
          "percentile_97": 5,
          "percentile_99": 7
        },
        "delivery_date_confidence": 0.76,
        "estimated_transit_days": 2,
        "ship_on_date": "2025-05-17"
      },
      "service": "groundadvantage"
    },
    {
      "carrier": "usps",
      "easypost_time_in_transit_data": {
        "days_in_transit": {
          "percentile_50": 2,
          "percentile_75": 2,
          "percentile_85": 2,
          "percentile_90": 3,
          "percentile_95": 4,
          "percentile_97": 4,
          "percentile_99": 6
        },
        "delivery_date_confidence": 0.81,
        "estimated_transit_days": 2,
        "ship_on_date": "2025-05-17"
      },
      "service": "librarymail"
    },
    {
      "carrier": "usps",
      "easypost_time_in_transit_data": {
        "days_in_transit": {
          "percentile_50": 2,
          "percentile_75": 2,
          "percentile_85": 3,
          "percentile_90": 3,
          "percentile_95": 4,
          "percentile_97": 5,
          "percentile_99": 6
        },
        "delivery_date_confidence": 0.79,
        "estimated_transit_days": 2,
        "ship_on_date": "2025-05-17"
      },
      "service": "mediamail"
    },
    {
      "carrier": "usps",
      "easypost_time_in_transit_data": {
        "days_in_transit": {
          "percentile_50": 2,
          "percentile_75": 2,
          "percentile_85": 3,
          "percentile_90": 3,
          "percentile_95": 4,
          "percentile_97": 5,
          "percentile_99": 6
        },
        "delivery_date_confidence": 0.76,
        "estimated_transit_days": 2,
        "ship_on_date": "2025-05-17"
      },
      "service": "priority"
    }
  ],
  "saturday_delivery": false,
  "to_zip": "10002"
}

Smart Deliver By

The /smartrate/deliver_by endpoint offers advanced predictions of delivery dates based on the entry point into the mailstream and intended delivery timelines.

No shipment ID is required.

Call the /smartrate/deliver_by endpoint by passing the from_zip, to_zip, an array of carriers, and the date the shipment will enter the mailstream using the planned_ship_date attribute. Analyze the returned easypost_time_in_transit_data object.

NOTE: Because this API does not require a shipment ID, it will only return time in transit data and no rates.

Request Parameters

from_zip
REQUIRED
i.e. "10001"
Specifies the postal code from which the shipment will originate.
planned_ship_date
REQUIRED
i.e. "2024-07-18"
The date the shipment is expected to enter the mailstream, crucial for accurate transit time estimates.
to_zip
REQUIRED
i.e. "10001"
Specifies the postal code to which the shipment is destined.
carriers
REQUIRED
i.e. ["UPS"]
Specifies the carriers to use.
saturday_delivery
OPTIONAL
i.e. false
Optional, whether to include Saturday deliveries in results or not.
POST /smartrate/deliver_by
1curl -X POST https://api.easypost.com/v2/smartrate/deliver_by \
2  -u "EASYPOST_API_KEY": \
3  -H 'Content-Type: application/json' \
4  -d '{
5    "from_zip": "10001",
6    "planned_ship_date": "2024-07-18",
7    "to_zip": "10002",
8    "carriers": [UPS],
9  }'
Response
1{
2  "carriers_without_tint_estimates": null,
3  "from_zip": "10001",
4  "planned_ship_date": "2025-05-19",
5  "results": [
6    {
7      "carrier": "usps",
8      "easypost_time_in_transit_data": {
9        "days_in_transit": {
10          "percentile_50": 1,
11          "percentile_75": 2,
12          "percentile_85": 2,
13          "percentile_90": 2,
14          "percentile_95": 3,
15          "percentile_97": 4,
16          "percentile_99": 5
17        },
18        "easypost_estimated_delivery_date": "2025-05-20"
19      },
20      "service": "express"
21    },
22    {
23      "carrier": "usps",
24      "easypost_time_in_transit_data": {
25        "days_in_transit": {
26          "percentile_50": 2,
27          "percentile_75": 2,
28          "percentile_85": 2,
29          "percentile_90": 3,
30          "percentile_95": 3,
31          "percentile_97": 4,
32          "percentile_99": 8
33        },
34        "easypost_estimated_delivery_date": "2025-05-20"
35      },
36      "service": "groundadvantage"
37    },
38    {
39      "carrier": "usps",
40      "easypost_time_in_transit_data": {
41        "days_in_transit": {
42          "percentile_50": 1,
43          "percentile_75": 2,
44          "percentile_85": 2,
45          "percentile_90": 2,
46          "percentile_95": 3,
47          "percentile_97": 3,
48          "percentile_99": 5
49        },
50        "easypost_estimated_delivery_date": "2025-05-20"
51      },
52      "service": "librarymail"
53    },
54    {
55      "carrier": "usps",
56      "easypost_time_in_transit_data": {
57        "days_in_transit": {
58          "percentile_50": 2,
59          "percentile_75": 2,
60          "percentile_85": 2,
61          "percentile_90": 3,
62          "percentile_95": 3,
63          "percentile_97": 4,
64          "percentile_99": 8
65        },
66        "easypost_estimated_delivery_date": "2025-05-20"
67      },
68      "service": "mediamail"
69    },
70    {
71      "carrier": "usps",
72      "easypost_time_in_transit_data": {
73        "days_in_transit": {
74          "percentile_50": 2,
75          "percentile_75": 2,
76          "percentile_85": 2,
77          "percentile_90": 3,
78          "percentile_95": 3,
79          "percentile_97": 4,
80          "percentile_99": 5
81        },
82        "easypost_estimated_delivery_date": "2025-05-20"
83      },
84      "service": "priority"
85    }
86  ],
87  "saturday_delivery": false,
88  "to_zip": "10002"
89}

Smart Deliver On

The /smartrate/deliver_on endpoint of the Smart 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.

No shipment ID is required.

Call the /smartrate/deliver_on endpoint by passing the from_zip, to_zip, and an array of carriers along with the desired_delivery_date. Receive recommendations for shipping dates that align with the delivery goals.

This endpoint requires the desired_delivery_date parameter to generate highly accurate predictions.

NOTE: Because this API does not require a shipment ID, it will only return time in transit data and no rates.

Request Parameters

from_zip
REQUIRED
i.e. "10001"
Specifies the postal code from which the shipment will originate.
desired_delivery_date
REQUIRED
i.e. "2024-07-18"
Specify the target delivery date for the package. The API calculates the optimal shipping date to meet this requirement. Failure to provide this date results in a failed API call.
to_zip
REQUIRED
i.e. "10001"
Specifies the postal code to which the shipment is destined.
carriers
REQUIRED
i.e. ["UPS"]
Specifies the carriers to use.
saturday_delivery
OPTIONAL
i.e. false
Optional, whether to include Saturday deliveries in results or not.
POST /smartrate/deliver_on
1curl -X POST https://api.easypost.com/v2/smartrate/deliver_on \
2  -u "EASYPOST_API_KEY": \
3  -H 'Content-Type: application/json' \
4  -d '{
5    "from_zip": "10001",
6    "desired_delivery_date": "2024-07-18",
7    "to_zip": "10002",
8    "carriers": [UPS],
9  }'
Response
1{
2  "carriers_without_tint_estimates": null,
3  "desired_delivery_date": "2025-05-19",
4  "from_zip": "10001",
5  "results": [
6    {
7      "carrier": "usps",
8      "easypost_time_in_transit_data": {
9        "days_in_transit": {
10          "percentile_50": 2,
11          "percentile_75": 2,
12          "percentile_85": 3,
13          "percentile_90": 3,
14          "percentile_95": 4,
15          "percentile_97": 5,
16          "percentile_99": 8
17        },
18        "delivery_date_confidence": 0.68,
19        "estimated_transit_days": 2,
20        "ship_on_date": "2025-05-17"
21      },
22      "service": "express"
23    },
24    {
25      "carrier": "usps",
26      "easypost_time_in_transit_data": {
27        "days_in_transit": {
28          "percentile_50": 2,
29          "percentile_75": 2,
30          "percentile_85": 3,
31          "percentile_90": 3,
32          "percentile_95": 4,
33          "percentile_97": 5,
34          "percentile_99": 7
35        },
36        "delivery_date_confidence": 0.76,
37        "estimated_transit_days": 2,
38        "ship_on_date": "2025-05-17"
39      },
40      "service": "groundadvantage"
41    },
42    {
43      "carrier": "usps",
44      "easypost_time_in_transit_data": {
45        "days_in_transit": {
46          "percentile_50": 2,
47          "percentile_75": 2,
48          "percentile_85": 2,
49          "percentile_90": 3,
50          "percentile_95": 4,
51          "percentile_97": 4,
52          "percentile_99": 6
53        },
54        "delivery_date_confidence": 0.81,
55        "estimated_transit_days": 2,
56        "ship_on_date": "2025-05-17"
57      },
58      "service": "librarymail"
59    },
60    {
61      "carrier": "usps",
62      "easypost_time_in_transit_data": {
63        "days_in_transit": {
64          "percentile_50": 2,
65          "percentile_75": 2,
66          "percentile_85": 3,
67          "percentile_90": 3,
68          "percentile_95": 4,
69          "percentile_97": 5,
70          "percentile_99": 6
71        },
72        "delivery_date_confidence": 0.79,
73        "estimated_transit_days": 2,
74        "ship_on_date": "2025-05-17"
75      },
76      "service": "mediamail"
77    },
78    {
79      "carrier": "usps",
80      "easypost_time_in_transit_data": {
81        "days_in_transit": {
82          "percentile_50": 2,
83          "percentile_75": 2,
84          "percentile_85": 3,
85          "percentile_90": 3,
86          "percentile_95": 4,
87          "percentile_97": 5,
88          "percentile_99": 6
89        },
90        "delivery_date_confidence": 0.76,
91        "estimated_transit_days": 2,
92        "ship_on_date": "2025-05-17"
93      },
94      "service": "priority"
95    }
96  ],
97  "saturday_delivery": false,
98  "to_zip": "10002"
99}