SmartRate API Guidance

Table of Contents:

• How does the SmartRate API work?
• How can I access the SmartRate API?
• What transit time data is returned from the API?
• How are transit days calculated?
• How do I use the SmartRate API?
• When would I use the SmartRate API?
• How can I save money using the SmartRate API?
• How can I improve on-time delivery metrics using the SmartRate API?
• How can I improve transit time predictions for my end customers using the SmartRate API?

How does the SmartRate API work?

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 on a sophisticated model using actual historical data for the shipping lane in question.

How can I access the SmartRate API?

The SmartRate API is a paid add-on. Please email support@easypost.com to request access. 

What transit time data is returned from the API?

The SmartRate API returns a time in transit object with transit days across a variety of percentiles for every rate for a given Shipment.

How are transit days calculated?

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.

How do I use the SmartRate API?

To make a request to the SmartRate API, first, create a shipment, then make the SmartRate call using the shipment ID of the shipment you just created. Using the response, you can now make better data-driven decisions about which rate to select when purchasing a label. SmartRate API documentation can be found here.

Below is an example call made to the SmartRate:

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

Below is a sample response to a successful call made to the API to retrieve time in transit statistics across all rates for a shipment:

{
  "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"
      },
      {
          "carrier": "USPS",
          "carrier_account_id": "ca_...",
          "created_at": "2021-05-04T17:00:19Z",
          "currency": "USD",
          "delivery_date": null,
          "delivery_date_guaranteed": false,
          "delivery_days": 5,
          "est_delivery_days": 5,
          "id": "rate_...",
          "list_currency": "USD",
          "list_rate": 8.55,
          "mode": "production",
          "object": "Rate",
          "rate": 8.55,
          "retail_currency": "USD",
          "retail_rate": 8.55,
          "service": "ParcelSelect",
          "shipment_id": "shp_...",
          "time_in_transit": {
              "percentile_50": 2,
              "percentile_75": 3,
              "percentile_85": 4,
              "percentile_90": 5,
              "percentile_95": 6,
              "percentile_97": 7,
              "percentile_99": 10
          },
          "updated_at": "2021-05-04T17:00:19Z"
      },
{
          "carrier": "USPS",
          "carrier_account_id": "ca_...",
          "created_at": "2021-05-04T17:00:19Z",
          "currency": "USD",
          "delivery_date": null,
          "delivery_date_guaranteed": false,
          "delivery_days": null,
          "est_delivery_days": null,
          "id": "rate_...",
          "list_currency": "USD",
          "list_rate": 37.5,
          "mode": "production",
          "object": "Rate",
          "rate": 37.5,
          "retail_currency": "USD",
          "retail_rate": 44.5,
          "service": "Express",
          "shipment_id": "shp_...",
          "time_in_transit": {
              "percentile_50": 1,
              "percentile_75": 2,
              "percentile_85": 3,
              "percentile_90": 3,
              "percentile_95": 4,
              "percentile_97": 5,
              "percentile_99": 8
          },
          "updated_at": "2021-05-04T17:00:19Z"
      }
  ]
}

When would I use the SmartRate API?

The SmartRate API returns highly accurate transit time predictions on every shipment. The transit time predictions in the response are based on a sophisticated model using actual historical data for the shipping lane in question. 

You can use the SmartRate API any time you are looking for a more accurate prediction of transit times for your shipments and rates. We see this happen for many customers in two key scenarios:

• When purchasing a label. After creating a shipment, call the SmartRate API for all business rules and workflows related to leveraging time-in-transit predictions for the shipment. You can create new workflows using the guidance below!
  
  
• When publishing delivery estimates for your end customers. After creating a shipment, use the SmartRate API to pull accurate transit time predictions for your end customers. You can create new workflows using the guidance below!

How can I save money using the SmartRate API?

The SmartRate API returns highly accurate transit time predictions on every shipment. The transit time predictions in the response are based on a sophisticated model using actual historical data for the shipping lane in question. 

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 that 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 your Ground service level arrives at the customer’s location in 2 days 90% on time. You have built-in logic with the SmartRate API to select the cheapest rate under the 90% on-time percentile, so in this case, you 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. 

How can I improve on-time delivery metrics using the SmartRate API?

The SmartRate API returns highly accurate transit time predictions on every shipment. The transit time predictions in the response are based on a sophisticated model using actual historical data for the shipping lane in question. 

Opportunities arise to 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 that 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 your 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.  You have built-in logic with the SmartRate API to select the cheapest rate under the 90% on-time percentile, so in this case, you select the Next-day service level. 

Where you would previously default to selecting your 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.

How can I improve transit time predictions for my end customers using the SmartRate API?

The SmartRate API returns highly accurate transit time predictions on every shipment. The transit time predictions in the response are based on a sophisticated model using actual historical data for the shipping lane in question. 

Opportunities arise to improve transit time predictions for your end customers by using the API to supply time in transit predictions on your 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. You 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 your Ground service level arrives at the customer’s location in 2 days 90% on time. You have 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.