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 Object

{
  "carriers_without_tint_estimates": null,
  "desired_delivery_date": "2024-07-16",
  "from_zip": "94107",
  "results": [
    {
      "carrier": "USPS",
      "easypost_time_in_transit_data": {
        "days_in_transit": {
          "percentile_50": 2,
          "percentile_75": 2,
          "percentile_85": 2,
          "percentile_90": 3,
          "percentile_95": 3,
          "percentile_97": 4,
          "percentile_99": 7
        },
        "delivery_date_confidence": 0.47,
        "estimated_transit_days": 1,
        "ship_on_date": "2024-07-15"
      },
      "service": "express"
    },
    {
      "carrier": "USPS",
      "easypost_time_in_transit_data": {
        "days_in_transit": {
          "percentile_50": 2,
          "percentile_75": 3,
          "percentile_85": 4,
          "percentile_90": 4,
          "percentile_95": 5,
          "percentile_97": 5,
          "percentile_99": 9
        },
        "delivery_date_confidence": 0.21,
        "estimated_transit_days": 3,
        "ship_on_date": "2024-07-13"
      },
      "service": "groundadvantage"
    },
    {
      "carrier": "USPS",
      "easypost_time_in_transit_data": {
        "days_in_transit": {
          "percentile_50": 2,
          "percentile_75": 3,
          "percentile_85": 4,
          "percentile_90": 4,
          "percentile_95": 5,
          "percentile_97": 6,
          "percentile_99": 9
        },
        "delivery_date_confidence": 0.25,
        "estimated_transit_days": 3,
        "ship_on_date": "2024-07-13"
      },
      "service": "librarymail"
    },
    {
      "carrier": "USPS",
      "easypost_time_in_transit_data": {
        "days_in_transit": {
          "percentile_50": 2,
          "percentile_75": 3,
          "percentile_85": 3,
          "percentile_90": 4,
          "percentile_95": 5,
          "percentile_97": 5,
          "percentile_99": 7
        },
        "delivery_date_confidence": 0.24,
        "estimated_transit_days": 3,
        "ship_on_date": "2024-07-13"
      },
      "service": "mediamail"
    },
    {
      "carrier": "USPS",
      "easypost_time_in_transit_data": {
        "days_in_transit": {
          "percentile_50": 2,
          "percentile_75": 3,
          "percentile_85": 4,
          "percentile_90": 4,
          "percentile_95": 5,
          "percentile_97": 5,
          "percentile_99": 7
        },
        "delivery_date_confidence": 0.19,
        "estimated_transit_days": 3,
        "ship_on_date": "2024-07-13"
      },
      "service": "priority"
    }
  ],
  "saturday_delivery": null,
  "to_zip": "90277"
}

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": "94107",
4  "planned_ship_date": "2024-07-16",
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": 3,
14          "percentile_95": 3,
15          "percentile_97": 4,
16          "percentile_99": 6
17        },
18        "easypost_estimated_delivery_date": "2024-07-17"
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": 3,
28          "percentile_85": 3,
29          "percentile_90": 4,
30          "percentile_95": 6,
31          "percentile_97": 6,
32          "percentile_99": 9
33        },
34        "easypost_estimated_delivery_date": "2024-07-18"
35      },
36      "service": "groundadvantage"
37    },
38    {
39      "carrier": "USPS",
40      "easypost_time_in_transit_data": {
41        "days_in_transit": {
42          "percentile_50": 3,
43          "percentile_75": 3,
44          "percentile_85": 3,
45          "percentile_90": 6,
46          "percentile_95": 6,
47          "percentile_97": 6,
48          "percentile_99": 9
49        },
50        "easypost_estimated_delivery_date": "2024-07-18"
51      },
52      "service": "librarymail"
53    },
54    {
55      "carrier": "USPS",
56      "easypost_time_in_transit_data": {
57        "days_in_transit": {
58          "percentile_50": 3,
59          "percentile_75": 3,
60          "percentile_85": 3,
61          "percentile_90": 4,
62          "percentile_95": 6,
63          "percentile_97": 6,
64          "percentile_99": 9
65        },
66        "easypost_estimated_delivery_date": "2024-07-18"
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": 3,
76          "percentile_85": 3,
77          "percentile_90": 3,
78          "percentile_95": 4,
79          "percentile_97": 6,
80          "percentile_99": 7
81        },
82        "easypost_estimated_delivery_date": "2024-07-18"
83      },
84      "service": "priority"
85    }
86  ],
87  "saturday_delivery": null,
88  "to_zip": "90277"
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": "2024-07-16",
4  "from_zip": "94107",
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": 2,
13          "percentile_90": 3,
14          "percentile_95": 3,
15          "percentile_97": 4,
16          "percentile_99": 7
17        },
18        "delivery_date_confidence": 0.47,
19        "estimated_transit_days": 1,
20        "ship_on_date": "2024-07-15"
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": 3,
30          "percentile_85": 4,
31          "percentile_90": 4,
32          "percentile_95": 5,
33          "percentile_97": 5,
34          "percentile_99": 9
35        },
36        "delivery_date_confidence": 0.21,
37        "estimated_transit_days": 3,
38        "ship_on_date": "2024-07-13"
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": 3,
48          "percentile_85": 4,
49          "percentile_90": 4,
50          "percentile_95": 5,
51          "percentile_97": 6,
52          "percentile_99": 9
53        },
54        "delivery_date_confidence": 0.25,
55        "estimated_transit_days": 3,
56        "ship_on_date": "2024-07-13"
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": 3,
66          "percentile_85": 3,
67          "percentile_90": 4,
68          "percentile_95": 5,
69          "percentile_97": 5,
70          "percentile_99": 7
71        },
72        "delivery_date_confidence": 0.24,
73        "estimated_transit_days": 3,
74        "ship_on_date": "2024-07-13"
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": 3,
84          "percentile_85": 4,
85          "percentile_90": 4,
86          "percentile_95": 5,
87          "percentile_97": 5,
88          "percentile_99": 7
89        },
90        "delivery_date_confidence": 0.19,
91        "estimated_transit_days": 3,
92        "ship_on_date": "2024-07-13"
93      },
94      "service": "priority"
95    }
96  ],
97  "saturday_delivery": null,
98  "to_zip": "90277"
99}