# Shipping SmartRate

The Shipping SmartRate API provides shippers with highly accurate, shipment-level transit time predictions that can save money, improve on-time delivery, and provide end customers with reliable delivery estimates.

> Note: The SmartRate API is currently available exclusively for US domestic shipments.

---

## Shipping SmartRate

### Example: GET /shipments/:id/smartrate

#### cURL

```shell
curl -X GET https://api.easypost.com/v2/shipments/shp_.../smartrate \
  -u "EASYPOST_API_KEY":
```

#### Go

```go
package example

import (
	"fmt"

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

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

	smartRates, _ := client.GetShipmentSmartrates("shp_...")

	fmt.Println(smartRates)
}
```

#### Java

```java
package shipments;

import com.easypost.exception.EasyPostException;
import com.easypost.model.SmartRate;
import com.easypost.service.EasyPostClient;

import java.util.List;

public class RetrieveTimeInTransitStatistics {
    public static void main(String[] args) throws EasyPostException {
        EasyPostClient client = new EasyPostClient("EASYPOST_API_KEY");

        List<SmartRate> smartrates = client.shipment.smartRates("shp_...");

        System.out.println(smartrates);
    }
}
```

#### C#

```csharp
using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using EasyPost;
using Newtonsoft.Json;

namespace EasyPostExamples
{
    public class Examples
    {
        public static async Task Main()
        {
            var client = new EasyPost.Client(new EasyPost.ClientConfiguration("EASYPOST_API_KEY"));

            List<EasyPost.Models.API.SmartRate> smartRates = await client.Shipment.GetSmartRates("shp_...");

            Console.WriteLine(JsonConvert.SerializeObject(smartRates, Formatting.Indented));
        }
    }
}
```

#### Node.js

```javascript
const EasyPostClient = require('@easypost/api');

const client = new EasyPostClient('EASYPOST_API_KEY');

(async () => {
  const smartRates = await client.Shipment.getSmartrates('shp_...');

  console.log(smartRates);
})();
```

#### PHP

```php
<?php

$client = new \EasyPost\EasyPostClient('EASYPOST_API_KEY');

$smartRates = $client->shipment->getSmartrates('shp_...');

echo $smartRates;
```

#### Python

```python
import easypost

client = easypost.EasyPostClient("EASYPOST_API_KEY")

smart_rates = client.shipment.get_smart_rates("shp_...")

print(smart_rates)
```

#### Ruby

```ruby
require 'easypost'

client = EasyPost::Client.new(api_key: 'EASYPOST_API_KEY')

shipment = client.shipment.get_smart_rates('shp_...')

puts shipment
```

The **/smartrate** endpoint accepts a `Shipment ID` and
returns a `time_in_transit object` that
includes transit business days across various percentiles for every `Rate` associated with a given

`Shipment`. Transit business days are calculated as the number of business days
(Monday-Friday) from when the carrier first acknowledges possession of the shipment to the initial out-for-delivery
attempt.

`Create a Shipment`. Based on the shipping schedule or delivery
requirements, choose the appropriate SmartRate endpoint and call it by passing the **shipment_id**. Use the response to
select the most appropriate rate for the shipment.

---

## TimeInTransit object

| Property | Type | Description |
|----------|------|-------------|
| percentile_50 | integer | Expected transit days at the 50th percentile |
| percentile_75 | integer | Expected transit days at the 75th percentile |
| percentile_85 | integer | Expected transit days at the 85th percentile |
| percentile_90 | integer | Expected transit days at the 90th percentile |
| percentile_95 | integer | Expected transit days at the 95th percentile |
| percentile_97 | integer | Expected transit days at the 97th percentile |
| percentile_99 | integer | Expected transit days at the 99th percentile |

Example Object:

```json
{
  "result": [
    {
      "carrier": "USPS",
      "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac",
      "created_at": "2025-05-09T20:40:16Z",
      "currency": "USD",
      "delivery_date": null,
      "delivery_date_guaranteed": false,
      "delivery_days": 2,
      "est_delivery_days": 2,
      "id": "rate_2a7a421fb01d45b49d5b6e96d6872c1e",
      "list_currency": "USD",
      "list_rate": 51.2,
      "mode": "test",
      "object": "Rate",
      "rate": 51.2,
      "retail_currency": "USD",
      "retail_rate": 59.25,
      "service": "Express",
      "shipment_id": "shp_270e4e8f5f8b4d9a9b040cefbb8a9694",
      "time_in_transit": {
        "percentile_50": 2,
        "percentile_75": 2,
        "percentile_85": 3,
        "percentile_90": 3,
        "percentile_95": 4,
        "percentile_97": 5,
        "percentile_99": 8
      },
      "updated_at": "2025-05-09T20:40:16Z"
    },
    {
      "carrier": "USPS",
      "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac",
      "created_at": "2025-05-09T20:40:16Z",
      "currency": "USD",
      "delivery_date": null,
      "delivery_date_guaranteed": false,
      "delivery_days": 2,
      "est_delivery_days": 2,
      "id": "rate_da69b97ddd5847dca7cbb2628d7150df",
      "list_currency": "USD",
      "list_rate": 11.01,
      "mode": "test",
      "object": "Rate",
      "rate": 11.01,
      "retail_currency": "USD",
      "retail_rate": 15.4,
      "service": "Priority",
      "shipment_id": "shp_270e4e8f5f8b4d9a9b040cefbb8a9694",
      "time_in_transit": {
        "percentile_50": 2,
        "percentile_75": 2,
        "percentile_85": 2,
        "percentile_90": 2,
        "percentile_95": 3,
        "percentile_97": 4,
        "percentile_99": 5
      },
      "updated_at": "2025-05-09T20:40:16Z"
    },
    {
      "carrier": "USPS",
      "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac",
      "created_at": "2025-05-09T20:40:16Z",
      "currency": "USD",
      "delivery_date": null,
      "delivery_date_guaranteed": false,
      "delivery_days": 3,
      "est_delivery_days": 3,
      "id": "rate_35608b7b51c64bbf93ca16d96ad86d54",
      "list_currency": "USD",
      "list_rate": 9.74,
      "mode": "test",
      "object": "Rate",
      "rate": 8.2,
      "retail_currency": "USD",
      "retail_rate": 13.85,
      "service": "GroundAdvantage",
      "shipment_id": "shp_270e4e8f5f8b4d9a9b040cefbb8a9694",
      "time_in_transit": {
        "percentile_50": 1,
        "percentile_75": 2,
        "percentile_85": 2,
        "percentile_90": 2,
        "percentile_95": 2,
        "percentile_97": 3,
        "percentile_99": 5
      },
      "updated_at": "2025-05-09T20:40:16Z"
    }
  ]
}
```

---

## Delivery Date

### Example: GET /shipments/:id/smartrate/delivery_date

#### cURL

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

#### Go

```go
package example

import (
	"fmt"

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

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

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

	fmt.Println(estimatedDeliveryDates)
}
```

#### Java

```java
package shipments;

import com.easypost.exception.EasyPostException;
import com.easypost.model.Shipment;
import com.easypost.model.EstimatedDeliveryDate;
import com.easypost.service.EasyPostClient;

import java.util.List;

public class RetrieveEstimatedDeliveryDate {
    public static void main(String[] args) throws EasyPostException {
        EasyPostClient client = new EasyPostClient("EASYPOST_API_KEY");

        Shipment shipment = client.shipment.retrieve("shp_...");
        List<EstimatedDeliveryDate> estimatedDeliveryDates = client
                .shipmentretrieveEstimatedDeliveryDate(shipment.getId(), "YYYY-MM-DD");

        System.out.println(estimatedDeliveryDates);
    }
}
```

#### C#

```csharp
using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using EasyPost;
using Newtonsoft.Json;

namespace EasyPostExamples
{
    public class Examples
    {
        public static async Task Main()
        {
            var client = new EasyPost.Client(new EasyPost.ClientConfiguration("EASYPOST_API_KEY"));

            EasyPost.Parameters.Shipment.RetrieveEstimatedDeliveryDate parameters = new()
            {
                PlannedShipDate = "2021-01-01",
            };

            List<EasyPost.Models.API.RateWithEstimatedDeliveryDate> rates = await client.Shipment.RetrieveEstimatedDeliveryDate("shp_...", parameters);

            Console.WriteLine(JsonConvert.SerializeObject(rates, Formatting.Indented));
        }
    }
}
```

#### Node.js

```javascript
const EasyPostClient = require('@easypost/api');

const client = new EasyPostClient('EASYPOST_API_KEY');

(async () => {
  const estimatedDeliveryDates = await client.Shipment.retrieveEstimatedDeliveryDate(
    'shp_...',
    'YYYY-MM-DD',
  );

  console.log(estimatedDeliveryDates);
})();
```

#### PHP

```php
<?php

$client = new \EasyPost\EasyPostClient('EASYPOST_API_KEY');

$estimatedDeliveryDates = $client->shipment->retrieveEstimatedDeliveryDate('shp_...', 'YYYY-MM-DD');

echo $estimatedDeliveryDates;
```

#### Python

```python
import easypost

client = easypost.EasyPostClient("EASYPOST_API_KEY")

estimated_delivery_dates = client.shipment.retrieve_estimated_delivery_date(
    "shp_...",
    planned_ship_date="YYYY-MM-DD",
)

print(estimated_delivery_dates)
```

#### Ruby

```ruby
require 'easypost'

client = EasyPost::Client.new(api_key: 'EASYPOST_API_KEY')

estimated_delivery_dates = client.shipment.retrieve_estimated_delivery_date(
  'shp_...',
  'YYYY-MM-DD',
)

puts estimated_delivery_dates
```

The **/delivery_date** endpoint provides estimated delivery dates for shipments, helping users identify cost-effective service levels and enhance delivery timeliness.

Call the **/delivery_date** endpoint by passing the **shipment_id** and the date the shipment will enter the mailstream using the **planned_ship_date** attribute.
Review the returned **easypost_time_in_transit_data** object.

---

## Precision Shipping

### Example: GET /shipments/:id/smartrate/precision_shipping

#### cURL

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

#### Go

```go
package example

import (
	"fmt"

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

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

	rates, _ := client.RecommendShipDateForShipment("shp_...", "YYYY-MM-DD")

	fmt.Println(rates)
}
```

#### Java

```java
package shipments;

import com.easypost.exception.EasyPostException;
import com.easypost.model.Shipment;
import com.easypost.model.RecommendShipDateForShipmentResult;
import com.easypost.service.EasyPostClient;

import java.util.List;

public class RetrieveRecommendShipDate {
    public static void main(String[] args) throws EasyPostException {
        EasyPostClient client = new EasyPostClient("EASYPOST_API_KEY");

        Shipment shipment = client.shipment.retrieve("shp_...");
        List<RecommendShipDateForShipmentResult> rates = client.shipment
                .recommendShipDate(shipment.getId(), "YYYY-MM-DD");

        System.out.println(rates);
    }
}
```

#### C#

```csharp
using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using EasyPost;
using Newtonsoft.Json;

namespace EasyPostExamples
{
    public class Examples
    {
        public static async Task Main()
        {
            var client = new EasyPost.Client(new EasyPost.ClientConfiguration("EASYPOST_API_KEY"));

            EasyPost.Parameters.Shipment.RecommendShipDateForShipment parameters = new()
            {
                DesiredDeliveryDate = "2024-07-18",
            };

            List<EasyPost.Models.API.RecommendShipDateForShipmentResult> rates = await client.Shipment.RecommendShipDate("shp_...", parameters);

            Console.WriteLine(JsonConvert.SerializeObject(rates, Formatting.Indented));
        }
    }
}
```

#### Node.js

```javascript
const EasyPostClient = require('@easypost/api');

const client = new EasyPostClient('EASYPOST_API_KEY');

(async () => {
  const rates = await client.Shipment.recommendShipDate('shp_...', 'YYYY-MM-DD');

  console.log(rates);
})();
```

#### PHP

```php
<?php

$client = new \EasyPost\EasyPostClient('EASYPOST_API_KEY');

$rates = $client->shipment->recommendShipDate('shp_...', 'YYYY-MM-DD');

echo $rates;
```

#### Python

```python
import easypost

client = easypost.EasyPostClient("EASYPOST_API_KEY")

estimated_delivery_dates = client.shipment.recommend_ship_date(
    "shp_...",
    desired_delivery_date="YYYY-MM-DD",
)

print(estimated_delivery_dates)
```

#### Ruby

```ruby
require 'easypost'

client = EasyPost::Client.new(api_key: 'EASYPOST_API_KEY')

rates = client.shipment.recommend_ship_date(
  'shp_...',
  'YYYY-MM-DD',
)

puts rates
```

The **/precision_shipping** endpoint of the SmartRate 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.

Call the **/precision_shipping** endpoint by passing the shipment_id into the API request along with the **desired_delivery_date**.
Utilize the returned data to plan shipments precisely.

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