SmartRate Guide

This guide will teach you how to use the /delivery_date endpoint for EasyPost's SmartRate API, how to understand the API response, and explain key use cases.

The SmartRate API is a paid add-on. All users get 500 lifetime SmartRate API calls free to test the API. Users can either pay per call or sign up for a subscription.

The SmartRate API allows you to receive highly accurate, Shipment-level transit time predictions for your rated shipments. You can then use that data to make informed decisions about your shipping to save money, improve on-time delivery, and get reliable estimated delivery dates.

Step 1: Create a Shipment

To use SmartRate, you'll need to first create a Shipment for your Parcel. Once the Shipment is created, copy the shipment_id at the bottom of the response for the next step. You can view our Getting Started Guide for more information on how to create a Shipment.

Here is an example:

Create a Shipment
package example

import (
	"fmt"

	"github.com/EasyPost/easypost-go/v3"
)

func main() {
	client := easypost.New("EASYPOST_API_KEY")

	shipment, _ := client.CreateShipment(
		&easypost.Shipment{
			ToAddress: &easypost.Address{
				Name:    "Dr. Steve Brule",
				Street1: "179 N Harbor Dr",
				City:    "Redondo Beach",
				State:   "CA",
				Zip:     "90277",
				Country: "US",
				Phone:   "4155559999",
				Email:   "dr_steve_brule@gmail.com",
			},
			FromAddress: &easypost.Address{
				Name:    "EasyPost",
				Street1: "417 Montgomery Street",
				Street2: "5th Floor",
				City:    "San Francisco",
				State:   "CA",
				Zip:     "90277",
				Country: "US",
				Phone:   "4155559999",
				Email:   "support@easypost.com",
			},
			Parcel: &easypost.Parcel{
				Length: 20.2,
				Width:  10.9,
				Height: 5,
				Weight: 65.9,
			},
			CustomsInfo: &easypost.CustomsInfo{
				ID: "cstinfo_...",
			},
		},
	)

	fmt.Println(shipment)
}
Shipment JSON Response
{
  "created_at": "2024-01-24T00:07:30Z",
  "is_return": false,
  "messages": [],
  "mode": "test",
  "options": {
    "currency": "USD",
    "payment": {
      "type": "SENDER"
    },
    "date_advance": 0
  },
  "reference": null,
  "status": "unknown",
  "tracking_code": null,
  "updated_at": "2024-01-24T00:07:30Z",
  "batch_id": null,
  "batch_status": null,
  "batch_message": null,
  "customs_info": {
    "id": "cstinfo_657b430669ef456584bc4b82b3271084",
    "object": "CustomsInfo",
    "created_at": "2024-01-24T00:07:30Z",
    "updated_at": "2024-01-24T00:07:30Z",
    "contents_explanation": "",
    "contents_type": "merchandise",
    "customs_certify": true,
    "customs_signer": "Steve Brule",
    "eel_pfc": "NOEEI 30.37(a)",
    "non_delivery_option": "return",
    "restriction_comments": null,
    "restriction_type": "none",
    "mode": "test",
    "declaration": null,
    "customs_items": [
      {
        "id": "cstitem_046758e6b61847f99623c4d2290a26bd",
        "object": "CustomsItem",
        "created_at": "2024-01-24T00:07:30Z",
        "updated_at": "2024-01-24T00:07:30Z",
        "description": "T-shirt",
        "hs_tariff_number": "123456",
        "origin_country": "US",
        "quantity": 1,
        "value": "10.0",
        "weight": 5.0,
        "code": "123",
        "mode": "test",
        "manufacturer": null,
        "currency": null,
        "eccn": null,
        "printed_commodity_identifier": null
      }
    ]
  },
  "from_address": {
    "id": "adr_90e0406bba4c11eea7d53cecef1b359e",
    "object": "Address",
    "created_at": "2024-01-24T00:07:30+00:00",
    "updated_at": "2024-01-24T00:07:30+00:00",
    "name": "EasyPost",
    "company": null,
    "street1": "417 Montgomery Street",
    "street2": "5th Floor",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94104",
    "country": "US",
    "phone": "4153334445",
    "email": "support@easypost.com",
    "mode": "test",
    "carrier_facility": null,
    "residential": null,
    "federal_tax_id": null,
    "state_tax_id": null,
    "verifications": {}
  },
  "insurance": null,
  "order_id": null,
  "parcel": {
    "id": "prcl_4dde100b45af43acbe9c68244fa51851",
    "object": "Parcel",
    "created_at": "2024-01-24T00:07:30Z",
    "updated_at": "2024-01-24T00:07:30Z",
    "length": 20.2,
    "width": 10.9,
    "height": 5.0,
    "predefined_package": null,
    "weight": 65.9,
    "mode": "test"
  },
  "postage_label": null,
  "rates": [
    {
      "id": "rate_3cbb8d9c4ea1477588a17b0ee3e0c5b4",
      "object": "Rate",
      "created_at": "2024-01-24T00:07:30Z",
      "updated_at": "2024-01-24T00:07:30Z",
      "mode": "test",
      "service": "Express",
      "carrier": "USPS",
      "rate": "49.60",
      "currency": "USD",
      "retail_rate": "57.40",
      "retail_currency": "USD",
      "list_rate": "49.60",
      "list_currency": "USD",
      "billing_type": "easypost",
      "delivery_days": null,
      "delivery_date": null,
      "delivery_date_guaranteed": false,
      "est_delivery_days": null,
      "shipment_id": "shp_93170d48eb1a413aa5c0d8bf4384a350",
      "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
    },
    {
      "id": "rate_c9e1a6c4be1e40a7af83b42d1115c550",
      "object": "Rate",
      "created_at": "2024-01-24T00:07:30Z",
      "updated_at": "2024-01-24T00:07:30Z",
      "mode": "test",
      "service": "Priority",
      "carrier": "USPS",
      "rate": "7.33",
      "currency": "USD",
      "retail_rate": "15.20",
      "retail_currency": "USD",
      "list_rate": "10.89",
      "list_currency": "USD",
      "billing_type": "easypost",
      "delivery_days": 2,
      "delivery_date": null,
      "delivery_date_guaranteed": false,
      "est_delivery_days": 2,
      "shipment_id": "shp_93170d48eb1a413aa5c0d8bf4384a350",
      "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
    },
    {
      "id": "rate_a39910cfd937402fb77a9eaed223dcfe",
      "object": "Rate",
      "created_at": "2024-01-24T00:07:30Z",
      "updated_at": "2024-01-24T00:07:30Z",
      "mode": "test",
      "service": "GroundAdvantage",
      "carrier": "USPS",
      "rate": "6.79",
      "currency": "USD",
      "retail_rate": "13.15",
      "retail_currency": "USD",
      "list_rate": "9.41",
      "list_currency": "USD",
      "billing_type": "easypost",
      "delivery_days": 3,
      "delivery_date": null,
      "delivery_date_guaranteed": false,
      "est_delivery_days": 3,
      "shipment_id": "shp_93170d48eb1a413aa5c0d8bf4384a350",
      "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
    },
    {
      "id": "rate_d0b494c33c3e42f893b619d730f24058",
      "object": "Rate",
      "created_at": "2024-01-24T00:07:30Z",
      "updated_at": "2024-01-24T00:07:30Z",
      "mode": "test",
      "service": "First",
      "carrier": "USPS",
      "rate": "6.79",
      "currency": "USD",
      "retail_rate": "13.15",
      "retail_currency": "USD",
      "list_rate": "9.41",
      "list_currency": "USD",
      "billing_type": "easypost",
      "delivery_days": 3,
      "delivery_date": null,
      "delivery_date_guaranteed": false,
      "est_delivery_days": 3,
      "shipment_id": "shp_93170d48eb1a413aa5c0d8bf4384a350",
      "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
    },
    {
      "id": "rate_dad1a54ef6f64dfc9def001cbbb2b142",
      "object": "Rate",
      "created_at": "2024-01-24T00:07:30Z",
      "updated_at": "2024-01-24T00:07:30Z",
      "mode": "test",
      "service": "ParcelSelect",
      "carrier": "USPS",
      "rate": "6.79",
      "currency": "USD",
      "retail_rate": "13.15",
      "retail_currency": "USD",
      "list_rate": "9.41",
      "list_currency": "USD",
      "billing_type": "easypost",
      "delivery_days": 3,
      "delivery_date": null,
      "delivery_date_guaranteed": false,
      "est_delivery_days": 3,
      "shipment_id": "shp_93170d48eb1a413aa5c0d8bf4384a350",
      "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
    }
  ],
  "refund_status": null,
  "scan_form": null,
  "selected_rate": null,
  "tracker": null,
  "to_address": {
    "id": "adr_90dd5fb4ba4c11ee9e88ac1f6bc539ae",
    "object": "Address",
    "created_at": "2024-01-24T00:07:30+00:00",
    "updated_at": "2024-01-24T00:07:30+00:00",
    "name": "Dr. Steve Brule",
    "company": null,
    "street1": "179 N Harbor Dr",
    "street2": null,
    "city": "Redondo Beach",
    "state": "CA",
    "zip": "90277",
    "country": "US",
    "phone": "8573875756",
    "email": "dr_steve_brule@gmail.com",
    "mode": "test",
    "carrier_facility": null,
    "residential": null,
    "federal_tax_id": null,
    "state_tax_id": null,
    "verifications": {}
  },
  "usps_zone": 4,
  "return_address": {
    "id": "adr_90e0406bba4c11eea7d53cecef1b359e",
    "object": "Address",
    "created_at": "2024-01-24T00:07:30+00:00",
    "updated_at": "2024-01-24T00:07:30+00:00",
    "name": "EasyPost",
    "company": null,
    "street1": "417 Montgomery Street",
    "street2": "5th Floor",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94104",
    "country": "US",
    "phone": "4153334445",
    "email": "support@easypost.com",
    "mode": "test",
    "carrier_facility": null,
    "residential": null,
    "federal_tax_id": null,
    "state_tax_id": null,
    "verifications": {}
  },
  "buyer_address": {
    "id": "adr_90dd5fb4ba4c11ee9e88ac1f6bc539ae",
    "object": "Address",
    "created_at": "2024-01-24T00:07:30+00:00",
    "updated_at": "2024-01-24T00:07:30+00:00",
    "name": "Dr. Steve Brule",
    "company": null,
    "street1": "179 N Harbor Dr",
    "street2": null,
    "city": "Redondo Beach",
    "state": "CA",
    "zip": "90277",
    "country": "US",
    "phone": "8573875756",
    "email": "dr_steve_brule@gmail.com",
    "mode": "test",
    "carrier_facility": null,
    "residential": null,
    "federal_tax_id": null,
    "state_tax_id": null,
    "verifications": {}
  },
  "forms": [],
  "fees": [],
  "id": "shp_93170d48eb1a413aa5c0d8bf4384a350",
  "object": "Shipment"
}

Step 2: Call the SmartRate API

Next call the SmartRate API by passing your shipment_id into the API request and the date your shipment will enter the mail stream using the planned_ship_date attribute.

The SmartRate API will return the easypost_time_in_transit_data object that houses the easypost_estimated_delivery_date, planned_ship_date, and days_in_transit attributes. This data can be used to identify cheaper service levels that meet your time-in-transit SLAs, increase on-time delivery percentages for time-sensitive shipments, and improve customer experience with more accurate delivery date estimates.

Here is an example:

Call SmartRate
package example

import (
	"fmt"

	"github.com/EasyPost/easypost-go/v3"
)

func main() {
	client := easypost.New("EASYPOST_API_KEY")

	shipment, _ := client.GetShipment("shp_...")
	estimatedDeliveryDates, _ := client.GetShipmentEstimatedDeliveryDate(shipment.ID, "YYYY-MM-DD")

	fmt.Println(estimatedDeliveryDates)
}
SmartRate Response
{
  "rates": [
    {
      "easypost_time_in_transit_data": {
        "days_in_transit": {
          "percentile_50": 3,
          "percentile_75": 3,
          "percentile_85": 6,
          "percentile_90": 6,
          "percentile_95": 6,
          "percentile_97": 6,
          "percentile_99": 9
        },
        "easypost_estimated_delivery_date": "2024-01-26",
        "planned_ship_date": "2024-01-24"
      },
      "rate": {
        "carrier": "USPS",
        "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac",
        "created_at": "2024-01-24T00:07:45Z",
        "currency": "USD",
        "delivery_date": null,
        "delivery_date_guaranteed": false,
        "delivery_days": 3,
        "est_delivery_days": 3,
        "id": "rate_36a64db214ab4fafaeaaad6855ebf422",
        "list_currency": "USD",
        "list_rate": 9.41,
        "mode": "test",
        "object": "Rate",
        "rate": 6.79,
        "retail_currency": "USD",
        "retail_rate": 13.15,
        "service": "GroundAdvantage",
        "shipment_id": "shp_e3ce96ba8b6745608fe1c419d76b8fb5",
        "updated_at": "2024-01-24T00:07:45Z"
      }
    },
    {
      "easypost_time_in_transit_data": {
        "days_in_transit": {
          "percentile_50": 3,
          "percentile_75": 3,
          "percentile_85": 6,
          "percentile_90": 6,
          "percentile_95": 6,
          "percentile_97": 6,
          "percentile_99": 9
        },
        "easypost_estimated_delivery_date": "2024-01-26",
        "planned_ship_date": "2024-01-24"
      },
      "rate": {
        "carrier": "USPS",
        "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac",
        "created_at": "2024-01-24T00:07:45Z",
        "currency": "USD",
        "delivery_date": null,
        "delivery_date_guaranteed": false,
        "delivery_days": 3,
        "est_delivery_days": 3,
        "id": "rate_90170bc6328b46cda598d683828d6ac6",
        "list_currency": "USD",
        "list_rate": 9.41,
        "mode": "test",
        "object": "Rate",
        "rate": 6.79,
        "retail_currency": "USD",
        "retail_rate": 13.15,
        "service": "First",
        "shipment_id": "shp_e3ce96ba8b6745608fe1c419d76b8fb5",
        "updated_at": "2024-01-24T00:07:45Z"
      }
    },
    {
      "easypost_time_in_transit_data": {
        "days_in_transit": {
          "percentile_50": 3,
          "percentile_75": 3,
          "percentile_85": 6,
          "percentile_90": 6,
          "percentile_95": 6,
          "percentile_97": 6,
          "percentile_99": 9
        },
        "easypost_estimated_delivery_date": "2024-01-26",
        "planned_ship_date": "2024-01-24"
      },
      "rate": {
        "carrier": "USPS",
        "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac",
        "created_at": "2024-01-24T00:07:45Z",
        "currency": "USD",
        "delivery_date": null,
        "delivery_date_guaranteed": false,
        "delivery_days": 3,
        "est_delivery_days": 3,
        "id": "rate_ca519ed1f83d4a8ebc5c17a1dbe96553",
        "list_currency": "USD",
        "list_rate": 9.41,
        "mode": "test",
        "object": "Rate",
        "rate": 6.79,
        "retail_currency": "USD",
        "retail_rate": 13.15,
        "service": "ParcelSelect",
        "shipment_id": "shp_e3ce96ba8b6745608fe1c419d76b8fb5",
        "updated_at": "2024-01-24T00:07:45Z"
      }
    },
    {
      "easypost_time_in_transit_data": {
        "days_in_transit": {
          "percentile_50": 1,
          "percentile_75": 2,
          "percentile_85": 2,
          "percentile_90": 3,
          "percentile_95": 3,
          "percentile_97": 6,
          "percentile_99": 7
        },
        "easypost_estimated_delivery_date": "2024-01-25",
        "planned_ship_date": "2024-01-24"
      },
      "rate": {
        "carrier": "USPS",
        "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac",
        "created_at": "2024-01-24T00:07:45Z",
        "currency": "USD",
        "delivery_date": null,
        "delivery_date_guaranteed": false,
        "delivery_days": null,
        "est_delivery_days": null,
        "id": "rate_30c5c922506445a88b51212c52ac2db3",
        "list_currency": "USD",
        "list_rate": 49.6,
        "mode": "test",
        "object": "Rate",
        "rate": 49.6,
        "retail_currency": "USD",
        "retail_rate": 57.4,
        "service": "Express",
        "shipment_id": "shp_e3ce96ba8b6745608fe1c419d76b8fb5",
        "updated_at": "2024-01-24T00:07:45Z"
      }
    },
    {
      "easypost_time_in_transit_data": {
        "days_in_transit": {
          "percentile_50": 2,
          "percentile_75": 3,
          "percentile_85": 3,
          "percentile_90": 6,
          "percentile_95": 6,
          "percentile_97": 6,
          "percentile_99": 8
        },
        "easypost_estimated_delivery_date": "2024-01-26",
        "planned_ship_date": "2024-01-24"
      },
      "rate": {
        "carrier": "USPS",
        "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac",
        "created_at": "2024-01-24T00:07:45Z",
        "currency": "USD",
        "delivery_date": null,
        "delivery_date_guaranteed": false,
        "delivery_days": 2,
        "est_delivery_days": 2,
        "id": "rate_4d9a5348efb44acbb25d162e1a692cb0",
        "list_currency": "USD",
        "list_rate": 10.89,
        "mode": "test",
        "object": "Rate",
        "rate": 7.33,
        "retail_currency": "USD",
        "retail_rate": 15.2,
        "service": "Priority",
        "shipment_id": "shp_e3ce96ba8b6745608fe1c419d76b8fb5",
        "updated_at": "2024-01-24T00:07:45Z"
      }
    }
  ]
}

Understanding Your SmartRate Response

As mentioned earlier, once you call the SmartRate API with your shipment_id the API will return the easypost_time_in_transit_data object. Below, we'll explain each attribute that is returned by this object.

  • easypost_estimated_delivery_date
    • This attribute will return our estimated delivery date for your shipment based on SmartRate's calculations in YYYY/MM/DD format. This includes weekends and holidays, and is mapped to every service level.
  • planned_ship_date
    • This attribute is where you input the date you expect their shipment to enter the mailstream when calling the API. The SmartRate API then calculates predictions based on this date for the most accurate transit time estimates. Remember to enter a date when calling the /delivery_date endpoint, otherwise the call will fail.
  • days_in_transit
    • This attribute returns estimated transit times for your rated shipments in total days including weekends and holidays. The attribute will return estimates at the 50, 75, 85, 90, 95, 97, and 99th percentile. For example, if SmartRate returns "3" for "percentile_90" for your rated shipment that means 90% of the time shipments with similar to and from ZIP codes deliver in 3 total days with that service level. If your shipment entered the mail stream on Thursday, it'll be out for delivery on Saturday 90% of the time.

Example Key Use Cases

Use Case 1: Save Money

  1. You can call the SmartRate API and identify the service level with the lowest cost that still meets your desired transit time. Without SmartRate, you have to rely on carrier estimates. SmartRate uses the time-in-transit performance for the zip codes in your to and from address on your shipment on every carrier service to provide highly accurate and granular estimates. With these estimates, you can know the percent likelihood that a cheaper service level will still arrive on time, unlocking cost-saving alternatives that you may not have considered before.
  2. If you ship perishable items, SmartRate could help you save on packaging costs. Because the API returns transit times in total days and is more accurate than carrier estimates, you can pack a shipment with only the necessary amount of ice.

Use Case 2: Enhance Customer Experience

  1. You can use SmartRate to improve your shipments' on-time delivery rate, even during peak season. SmartRate's estimates are highly accurate and created for your unique shipment instead of zone-to-zone generalizations. This is invaluable during peak season when carriers' delivery times may slow down and customer expectations are at their highest.
  2. Improve your checkout experience by using SmartRate to acquire a reliable estimated delivery date. You can pass through the easypost_estimated_delivery_date to your checkout page, so customers can more easily decide between which shipping service they want to purchase. Customers will no longer have to try and calculate when their package will arrive.

Congratulations! You've called SmartRate for your shipment with EasyPost! Next, use the data from SmartRate to choose the best suited service for your shipment. Check out our Full Reference API Documentation for more details.