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?
- How do I use the Delivery Date Endpoint of 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 can I provide my end customers the estimated date the package would be delivered on?
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.
To receive back the estimated delivery date for a shipment you can call the /delivery_date endpoint with a planned date that the package will be shipped on.
How can I access the SmartRate API?
The SmartRate API is available to all users.
**Please note that there are 500 free LIFETIME calls to this endpoint. Any request after the first 500 will incur an additional fee. This includes requests made while using your TEST API Key.
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.
| attribute | type | specification |
| percentile_50 | integer | expected transit time in business days at the 50th percentile |
| percentile_75 | integer | expected transit time in business days at the 75th percentile |
| percentile_85 | integer | expected transit time in business days at the 85th percentile |
| percentile_90 | integer | expected transit time in business days at the 90th percentile |
| percentile_95 | integer | expected transit time in business days at the 95th percentile |
| percentile_97 | integer | expected transit time in business days at the 97th percentile |
| percentile_99 | integer | expected transit time in business days at the 99th percentile |
The Delivery Date endpoint will return an easypost_time_in_transit_data object for each rate. This object will contain:
-
easypost_estimated_delivery_date, which is the most likely date that the shipment will be delivered on. -
planned_ship_date, which will be the date supplied to the API that denotes when the package is expected to be in the carrier’s possession. -
days_in_transit, which will be similar to the time in transit object above with the various percentiles, except these will be the expected total transit time including weekends and holidays.
How are transit days calculated?
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.
When calling the Delivery Date endpoint, transit days are calculated as the number of total days including weekends and holidays 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"
}
]
}
How do I use the Delivery Date Endpoint of the SmartRate API?
To make a request to the Delivery Date Endpoint, first, create a shipment, then make the SmartRate call to the delivery date endpoint using the shipment ID of the shipment you just created. When calling this endpoint, you’ll need to provide the date you plan on shipping your package as well. Using the response, you or your customers 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 Delivery Date endpoint:
curl -X GET https://api.easypost.com/v2/shipments/shp_.../smartrate/delivery_date?planned_ship_date=yyyy-mm-dd \
-u "$EASYPOST_API_KEY":
Below is a sample response to a successful call made to the API to retrieve time in transit statistics and estimated delivery dates across all rates for a shipment:
"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
},
}
]
When would I use the SmartRate API?
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?
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:
| service | rate | p_90 transit days | p_75 transit days |
| Ground | $8.76 | 2 | 2 |
| 2-day | $14.59 | 2 | 1 |
| Next-day | $17.15 | 1 | 1 |
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?
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:
| service | rate | p_90 transit days | p_75 transit days |
| Ground | $8.76 | 5 | 4 |
| 2-day | $14.59 | 3 | 2 |
| Next-day | $17.15 | 2 | 1 |
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?
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:
| service | rate | Carrier estimated transit days | SmartRate p_90 transit days |
| Ground | $8.76 | 3 | 2 |
| 2-day | $14.59 | 2 | 1 |
| Next-day | $17.15 | 1 |
1 |
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.
How can I provide my end customers the estimated date the package would be delivered on?
The Delivery Date endpoint of the SmartRate API will provide back the most likely date that your package will be delivered on.
To receive this, you’ll need to know the exact date that you plan on shipping your package out. This planned shipped date will have to be some time within the next 30 days. This is due to some carriers’ labels expiring within 30 days of purchasing them and rates can change from time to time making the output of the SmartRate API outdated.
With this, you can call the Delivery Date endpoint and receive back for each rate a easypost_time_in_transit_data object which will contain an easypost_estimated_delivery_date.
To have the most accurate results, call this API as close to the shipping date as possible.
Comments
0 comments
Article is closed for comments.