SmartRate API FAQs

To call the SmartRate API, create a shipment and make the SmartRate call using the Shipment ID. Call the API as close to the shipping date as possible for the most accurate results.

Using the response, you can now make better, data-driven decisions about which rate to select when purchasing a label.

The SmartRate API can be tested using Postman.

Please visit the SmartRate API Docs and the SmartRate Guide for more details. 

Request

curl -X GET https://api.easypost.com/v2/shipments/shp_.../smartrate \
 -u <YOUR_TEST/PRODUCTION_API_KEY>: \

Response

{
 "result": [
     {
         "carrier": "USPS",
         "carrier_account_id": "ca_...",
         "created_at": "2021-05-04T17:00:19Z",
         "currency": "USD",
         "delivery_date": null,
         "delivery_date_guaranteed": false,
         "delivery_days": 2,
         "est_delivery_days": 2,
         "id": "rate_...",
         "list_currency": "USD",
         "list_rate": 8.85,
         "mode": "production",
         "object": "Rate",
         "rate": 8.12,
         "retail_currency": "USD",
         "retail_rate": 11.1,
         "service": "Priority",
         "shipment_id": "shp_...",
         "time_in_transit": {
             "percentile_50": 2,
             "percentile_75": 3,
             "percentile_85": 3,
             "percentile_90": 3,
             "percentile_95": 4,
             "percentile_97": 4,
             "percentile_99": 6
         },
         "updated_at": "2021-05-04T17:00:19Z"
     },
 ]
}

The SmartRate API returns a time_in_transit object with transit days across a variety of percentiles for every rate for a given shipment.

When calling the SmartRate API, 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. 

Please note that transit days may be calculated differently depending on the SmartRate endpoint used.

Savings opportunities arise by using the API to select the cheapest rate available that meets your desired transit time parameters. 

For example, let’s pretend your internal targets for on-time delivery are 90%, and you have a customer who purchased an item with your 2-day shipping option. You pass through the customer’s shipment information to the SmartRate API and return the following information:

The SmartRate API shows that the Ground service level arrives at the customer’s location in 2 days 90% on time. There is built-in logic with the SmartRate API to select the cheapest rate under the 90% on-time percentile, So, in this case, you should select the ground service level.

Where you would previously default to selecting your 2-day service level, SmartRate unlocks the ability to save money on shipments using cheaper service levels that will still arrive on time.

Improve on-time delivery by using the API to select the best rate that meets your desired transit time parameters.

For example, let’s pretend your internal targets for on-time delivery are 90%, and you have a customer who purchased an item with your 2-day shipping option. You pass through the customer’s shipment information to the SmartRate API and return the following information:

The SmartRate API shows that the 2-day service level arrives at the customer’s location in 2 days only 75% on time, and arrives in 3 days 90% on time. There is built-in logic with the SmartRate API to select the cheapest rate under the 90% on-time percentile, so in this case, select the Next-day service level.

Where you would previously default to selecting the 2-day service level and risk your shipment arriving late, SmartRate empowers you to better hit your on-time delivery targets by providing on-time delivery percentiles for every rate on a given shipment.

Improve transit time predictions for end customers by using the API to supply time in transit predictions on all shipping options.

For example, let’s pretend your internal targets for on-time delivery are 90%, and you offer a 1-day, 2-day, and Ground service level to your customers as shipping options at checkout. Pass through the customer’s shipment information acquired on the checkout page to the SmartRate API and return the following information:

The SmartRate API shows that the Ground service level arrives at the customer’s location in 2 days 90% on time. There is built-in logic with the SmartRate API to pass through the estimated transit days for all of your rates under the 90% on-time percentile as transit time estimates for your shipping options. 

SmartRate shows your customer can elect to choose the Ground service level for a 2-day shipment or the 2-day service level for a next-day shipment. Your customer benefits from selecting the cheapest option for their delivery preferences without overspending unnecessarily.

While we do not offer the full functionality of all of our SmartRate endpoints through the EasyPost Create Label tool, we do automatically review shipments and provide SmartRate-powered label suggestions for qualifying shipments.

The SmartRate API will evaluate all applicable connected carrier and service levels and highlight the Best and Fastest labels for your shipment at no additional cost. SmartRate-powered shipping labels purchased through the Create Label tool will not count towards your lifetime free SmartRate API calls. If you prefer a different option, you may also choose a different service from the full list of shipping rates.

SmartRate has multiple endpoints to best optimize shipments for any user. Please review our recommendations below for guidance on which endpoint to use. If you have additional questions, please contact your dedicated Customer Success Manager, Support, or our team of shipping experts for more information.

• Required fields: EasyPost Shipment ID
• Provides accurate time in transit estimates in business days

Delivery Date Estimator

• Required fields: EasyPost Shipment ID and Planned Ship Date
  • If you do not have a Shipment ID and do not need rating information, then call the Smart Deliver By endpoint.
• Provides accurate time in transit estimates in total days.
• Provides an estimated delivery date.

Precision Shipping

• Required fields: EasyPost Shipment ID and Desired Delivery Date
  • If you do not have a Shipment ID and do not need rating information, then call the Smart Deliver On endpoint.
• Provides accurate time in transit estimates in total days.
• Provides recommended service levels and ship dates for your desired delivery date.

Yes! All EasyPost users are welcome to test the SmartRate API or any of the various endpoints to review if it is right for their business. 

Each EasyPost user gets 500 free lifetime calls to the SmartRate API, including calls made with a Test API Key. Any SmartRate calls made after this point will incur a fee per call.

The SmartRate API can be tested using Postman.

Time_in_transit is returned when calling the SmartRate endpoint and returns transit times in business days. Holidays and weekends are not accounted for.

Days_in_transit is returned when calling the Delivery Date and Precision Shipping endpoints. It returns transit times in total days, accounting for holidays and weekends.

Understanding the percentiles returned in the time_in_transit and days_in_transit objects is critical to correctly leveraging SmartRate. It's important to note that a percentile is not the same as a percentage.

Let’s use the example API response below to explain:

"rates": [
  {
    "easypost_time_in_transit_data": {
      "days_in_transit": {
        "percentile_50": 2,
        "percentile_75": 3,
        "percentile_85": 4,
        "percentile_90": 4,
        "percentile_95": 4,
        "percentile_97": 5,
        "percentile_99": 6
       }
    }
  }
]    

Let’s assume the percentiles above are based on data from 100 shipments. The distribution of days in transit will typically form a bell curve. Here's what each percentile represents:

• 50th Percentile (Median): This is the median value, indicating that 50% of the shipments are delivered within 2 days or less. It represents a typical scenario. 
• 75th Percentile: 75% of the shipments are delivered within 3 days or less. This provides an assurance that most shipments. will be delivered within this timeframe. 
• 85th and 90th Percentile: These indicate that 85% and 90% of the shipments, respectively, are expected to be delivered within 4 days. This helps set expectations for slightly longer deliveries.  
• 95th Percentile: At this level, 95% of the shipments are delivered within 4 days, showing a high probability of delivery within this period, even under less typical conditions. 
• 97th Percentile: Reflects that 97% of the shipments are expected to be delivered in 5 days or fewer, which is useful for setting expectations for near worst-case scenarios without being overly conservative. 
• 99th Percentile: This conservative estimate indicates that nearly all shipments (99%) are expected to be delivered within 6 days. This is useful for managing customer expectations in extreme cases. 

By understanding these percentiles, businesses can better plan their shipping strategies, manage customer expectations, and select shipping options that align with the desired balance between cost and delivery speed. This percentile data helps in making informed decisions, especially when punctuality is critical or when planning for logistics in varying conditions. 

The SmartRate API enables you to make better shipping decisions based on your business needs. To do so, call the endpoint that suits your needs and provide your Shipment ID alongside any other required information.

Once you get a response from SmartRate, select the shipping service that best supports your goals for either cost-savings, delivery time, or both based on SmartRate’s guidance and any business logic you’ve built.

To make a request to the Delivery Date endpoint, create a shipment, then make a SmartRate call to the Delivery Date endpoint using the Shipment ID and provide the Planned Ship Date, or the date you expect the shipment to enter the carrier mailstream. For example, this would be the date you drop off the shipment at a carrier location or have a scheduled pickup.

Using the response, you can now make better, data-driven decisions about which rate to select when purchasing a label.

The Delivery Date endpoint can be tested using Postman.

Please visit the SmartRate API Docs and the SmartRate Guide for more details. 

Request

curl -X GET https://api.easypost.com/v2/shipments/shp_.../smartrate/delivery_date?planned_ship_date=yyyy-mm-dd \
 -u "$EASYPOST_API_KEY"

Response

"rates": [
  {
    “rate”: {
      ...
      “service”: “Express”,
      “carrier”: “USPS”,
      ...
      “delivery_days”: null,
      “delivery_date”: null,
      “delivery_date_guaranteed”: false,
      “est_delivery_days”: null,
    },
    “easypost_time_in_transit_data”: {
      “easypost_estimated_delivery_date”: “2023-05-06”
      “planned_ship_date”: “2023-05-03”
      “days_in_transit”: {
        "percentile_50": 2,
        "percentile_75": 2,
        "percentile_85": 3,
        "percentile_90": 3,
        "percentile_95": 4,
        "percentile_97": 5,
        "percentile_99": 6
      },
   }
]

The Delivery Date endpoint returns a days_in_transit object with transit days across a variety of percentiles for every rate for a given shipment.

When calling the Delivery Date endpoint, transit days are calculated as the total 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.

Please note that transit days may be calculated differently depending on the SmartRate endpoint used.

By considering the Planned Ship Date and accounting for weekends and holidays in the calculations, the Delivery Date endpoint can provide major improvements to cost savings and on-time delivery.

For example, the Planned Ship Date enables the endpoint to provide more accurate estimates on average response because the API will account for varying transit trends associated with each day of the week. Hypothetically, the shipment may have a faster total transit time if shipped on a Tuesday when compared to a Monday.

For another example, let’s pretend you ship perishable goods and need to pack each order with ice and insulation material to ensure your customers don’t receive spoiled goods. You ship on a Thursday and choose a service level that tells you the transit time will be 2 business days. Because of the weekend, you pack enough ice and insulation for 4 days worth of transit. However, with the Delivery Date endpoint, you see that the total transit time will be 2 total days since the carrier you chose ships on Saturdays as well.

With the Delivery Date endpoint, you can accurately predict transit times, ultimately reducing shipping costs from the service levels you choose to the packing material itself.

The Delivery Date endpoint returns the easypost_time_in_transit_data object which contains the easypost_estimated_delivery_date parameter in the response. This response can be used to improve your customer’s shopping cart experience by passing this data through.

For example, let’s create a hypothetical shopping cart experience below:

For users who want to obtain the time in transit results only from the Delivery Date endpoint but do not have a Shipment ID, there is a supplemental endpoint called the Smart Deliver By API. This API takes in the from_zip, to_zip, an array of carriers, and the date the shipment will enter the mailstream using the planned_ship_date attribute.

Please visit the SmartRate API Docs and the SmartRate Guide for more details. 

 Below is an example call made to the Smart Deliver By endpoint:

 curl -X POST 'https://api.easypost.com/v2/smartrate/deliver_by\'
  -u "$EASYPOST_API_KEY" 
  --header 'Content-Type: application/json' \
  --data-raw '{
    "from_zip": "94513",
    "planned_ship_date": "2024-05-21",
    "saturday_delivery": true,
    "to_zip": "94127",
    "carriers": ["USPS", "UPSDAP"]
  }

To make a request to the Precision Shipping endpoint, create a shipment and then make the SmartRate call to the Precision Shipping endpoint using the Shipment ID of the shipment. 

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

The Delivery Date endpoint can be tested using Postman.

Request

curl -X GET https://api.easypost.com/v2/shipments/shp_.../smartrate/precision_shipping?desired_delivery_date=yyyy-mm-dd \
 -u "$EASYPOST_API_KEY"

Response

"rates": [
  {
    "easypost_time_in_transit_data": {
      "days_in_transit": {
        "percentile_50": 1,
        "percentile_75": 1,
        "percentile_85": 3,
        "percentile_90": 3,
        "percentile_95": 3,
        "percentile_97": 4,
        "percentile_99": 6
      },
      "delivery_date_confidence": 0.75,
      "desired_delivery_date": "2023-11-22",
      "estimated_transit_days": 1,
      "ship_on_date": "2023-11-21"
    },
    "rate": {
      "carrier": "USPS",
      "carrier_account_id": "ca_...",
      "created_at": "2023-11-09T19:18:52Z",
      "currency": "USD",
      "delivery_date": null,
      "delivery_date_guaranteed": false,
      "delivery_days": 1,
      "est_delivery_days": 1,
      "id": "rate_...",
      "list_currency": "USD",
      "list_rate": 7.79,
      "mode": "production",
      "object": "Rate",
      "rate": 6.73,
      "retail_currency": "USD",
      "retail_rate": 9.8,
      "service": "Priority",
      "shipment_id": "shp_...",
      "updated_at": "2023-11-09T19:18:52Z"
    }
  }
]

The Precision Shipping endpoint returns a days_in_transit object with transit days across a variety of percentiles for every rate for a given shipment. This is the same as the Delivery Date endpoint.

When calling the Precision Shipping endpoint, transit days are calculated as the total 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.

Please note that transit days may be calculated differently depending on the SmartRate endpoint used.

However, this is not the only data that the Precision Shipping endpoint returns. You’ll also receive a Rate object and the following parameters: 

• delivery_date_confidence
• desired_delivery_date
• estimated_transit_days
• ship_on_date

This information provides enabled carriers and service levels that will allow you to deliver the shipment on your desired delivery date when you need to ship your package, the estimated transit time, and a confidence rating for each service level. 

For users who want to obtain the time in transit results only from the Precision Shipping endpoint but do not have a Shipment ID, there is a supplemental endpoint called the Smart Deliver On API. This API takes in the from_zip, to_zip, an array of carriers, and the desired date on which the package should be delivered exactly.

Please visit the SmartRate API Docs and the SmartRate Guide for more details.

Request

curl -X POST 'https://api.easypost.com/v2/smartrate/deliver_on\'
 -u "$EASYPOST_API_KEY" 
 --header 'Content-Type: application/json' \
 --data-raw '{
  "from_zip": "94513",
  "desired_delivery_date": "2024-05-21",
  "saturday_delivery": true,
  "to_zip": "94127",
  "carriers": ["USPS", "UPSDAP"]
}