# SmartRate

The `Smart Deliver By` and `Smart Deliver On` endpoints are designed for precise delivery scheduling scenarios. The Smart Deliver By endpoint specifies a delivery deadline, while the Smart Deliver On endpoint enables setting a specific delivery date.

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

## SmartRate Object

| Property | Type | Description |
|----------|------|-------------|
| planned_ship_date | datetime | Date the shipment is expected to enter the mailstream. |
| easypost_estimated_delivery_date | datetime | Estimated delivery date for the shipment in YYYY/MM/DD format, including weekends and holidays. |
| desired_delivery_date | datetime | Target delivery date for the package. Failure to provide this date results in a failed API call. |
| days_in_transit | integer | Estimated transit times at various percentiles. These transit times include holidays and weekends. |
| delivery_date_confidence | integer | Indicates the likelihood (0-1 scale) of a package being delivered on the specified delivery date. |
| estimated_transit_days | integer | Total number of days expected for the package to be delivered on the desired delivery date, assuming it is shipped on the suggested ship_on_date. |
| ship_on_date | datetime | Recommended date for dispatching the package to the carrier to ensure delivery by the desired delivery date. |
| from_zip | string | Specifies the postal code from which the shipment will originate. |
| to_zip | string | Specifies the postal code to which the shipment is destined. |

Example Object:

```json
{
  "carriers_without_tint_estimates": null,
  "desired_delivery_date": "2025-05-19",
  "from_zip": "10001",
  "results": [
    {
      "carrier": "usps",
      "easypost_time_in_transit_data": {
        "days_in_transit": {
          "percentile_50": 2,
          "percentile_75": 2,
          "percentile_85": 3,
          "percentile_90": 3,
          "percentile_95": 4,
          "percentile_97": 5,
          "percentile_99": 8
        },
        "delivery_date_confidence": 0.68,
        "estimated_transit_days": 2,
        "ship_on_date": "2025-05-17"
      },
      "service": "express"
    },
    {
      "carrier": "usps",
      "easypost_time_in_transit_data": {
        "days_in_transit": {
          "percentile_50": 2,
          "percentile_75": 2,
          "percentile_85": 3,
          "percentile_90": 3,
          "percentile_95": 4,
          "percentile_97": 5,
          "percentile_99": 7
        },
        "delivery_date_confidence": 0.76,
        "estimated_transit_days": 2,
        "ship_on_date": "2025-05-17"
      },
      "service": "groundadvantage"
    },
    {
      "carrier": "usps",
      "easypost_time_in_transit_data": {
        "days_in_transit": {
          "percentile_50": 2,
          "percentile_75": 2,
          "percentile_85": 2,
          "percentile_90": 3,
          "percentile_95": 4,
          "percentile_97": 4,
          "percentile_99": 6
        },
        "delivery_date_confidence": 0.81,
        "estimated_transit_days": 2,
        "ship_on_date": "2025-05-17"
      },
      "service": "librarymail"
    },
    {
      "carrier": "usps",
      "easypost_time_in_transit_data": {
        "days_in_transit": {
          "percentile_50": 2,
          "percentile_75": 2,
          "percentile_85": 3,
          "percentile_90": 3,
          "percentile_95": 4,
          "percentile_97": 5,
          "percentile_99": 6
        },
        "delivery_date_confidence": 0.79,
        "estimated_transit_days": 2,
        "ship_on_date": "2025-05-17"
      },
      "service": "mediamail"
    },
    {
      "carrier": "usps",
      "easypost_time_in_transit_data": {
        "days_in_transit": {
          "percentile_50": 2,
          "percentile_75": 2,
          "percentile_85": 3,
          "percentile_90": 3,
          "percentile_95": 4,
          "percentile_97": 5,
          "percentile_99": 6
        },
        "delivery_date_confidence": 0.76,
        "estimated_transit_days": 2,
        "ship_on_date": "2025-05-17"
      },
      "service": "priority"
    }
  ],
  "saturday_delivery": false,
  "to_zip": "10002"
}
```

---

## Smart Deliver By

### Example: POST /smartrate/deliver_by

#### cURL

```shell
curl -X POST https://api.easypost.com/v2/smartrate/deliver_by \
  -u "EASYPOST_API_KEY": \
  -H 'Content-Type: application/json' \
  -d '{
    "from_zip": "10001",
    "planned_ship_date": "2024-07-18",
    "to_zip": "10002",
    "carriers": [UPS],
  }'
```

#### Go

```go
package example

import (
	"fmt"

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

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

	params := &easypost.EstimateDeliveryDateForZipPairParams{
		FromZip:         "10001",
		ToZip:           "10002",
		Carriers:        []string{"UPS", "FedEx"},
		PlannedShipDate: "2024-07-18",
	}

	estimates, _ := client.EstimateDeliveryDateForZipPair(params)

	fmt.Println(estimates)
}
```

#### Java

```java
package shipments;

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

import java.util.Collections;
import java.util.HashMap;
import java.util.Map;

public class RetrieveRecommendShipDate {
    public static void main(String[] args) throws EasyPostException {
        EasyPostClient client = new EasyPostClient("EASYPOST_API_KEY");
        Map<String, Object> params = new HashMap<String, Object>();
        params.put("from_zip", "10001");
        params.put("to_zip", "10002");
        params.put("planned_ship_date", "2024-07-18");
        params.put("carriers", Collections.singletonList("UPS"));

        EstimateDeliveryDateForZipPairResult results = client.smartRate
                .estimateDeliveryDate(params);

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

#### 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.SmartRate.EstimateDeliveryDateForZipPair estimateDeliveryDateForZipPairParameters = new()
            {
                OriginPostalCode = address1Parameters.Zip,
                DestinationPostalCode = address2Parameters.Zip,
                PlannedShipDate = Fixtures.PlannedShipDate,
                Carriers = ["USPS"],
            };

            EasyPost.Models.API.EstimateDeliveryDateForZipPairResult results = await client.SmartRate.EstimateDeliveryDate(estimateDeliveryDateForZipPairParameters);

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

#### Node.js

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

const client = new EasyPostClient('EASYPOST_API_KEY');

(async () => {
  const results = await client.SmartRate.estimateDeliveryDate({
    from_zip: '10001',
    to_zip: '10002',
    planned_ship_date: '2024-07-18',
    carriers: ['UPS'],
  });

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

#### PHP

```php
<?php

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

$results = $client->smartRate->estimateDeliveryDate([
    'from_zip' => '10001',
    'to_zip' => '10002',
    'planned_ship_date' => '2024-07-18',
    'carriers' => ['UPS'],
]);

echo $results;
```

#### Python

```python
import easypost

client = easypost.EasyPostClient("EASYPOST_API_KEY")

results = client.smartrate.estimate_delivery_date(
    from_zip="10001",
    to_zip="10002",
    planned_ship_date="2024-07-18",
    carriers=["usps"],
)

print(results)
```

#### Ruby

```ruby
require 'easypost'

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

results = client.smart_rate.estimate_delivery_date(
  from_zip: '10001',
  to_zip: '10002',
  planned_ship_date: '2024-07-18',
  carriers: ['ups'],
)

puts results
```

The **/smartrate/deliver_by** endpoint offers advanced predictions of delivery dates based on the entry point into the mailstream and intended delivery timelines.

No shipment ID is required.

Call the **/smartrate/deliver_by** endpoint by passing the **from_zip**, **to_zip**, an array of **carriers**, and the date the shipment will enter the mailstream using the **planned_ship_date** attribute.
Analyze the returned **easypost_time_in_transit_data** object.

**NOTE:** Because this API does not require a shipment ID, it will only return time in transit data and no rates.

---

## Smart Deliver On

### Example: POST /smartrate/deliver_on

#### cURL

```shell
curl -X POST https://api.easypost.com/v2/smartrate/deliver_on \
  -u "EASYPOST_API_KEY": \
  -H 'Content-Type: application/json' \
  -d '{
    "from_zip": "10001",
    "desired_delivery_date": "2024-07-18",
    "to_zip": "10002",
    "carriers": [UPS],
  }'
```

#### Go

```go
package example

import (
	"fmt"

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

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

	params := &easypost.RecommendShipDateForZipPairParams{
		FromZip:             "10001",
		ToZip:               "10002",
		Carriers:            []string{"UPS", "FedEx"},
		DesiredDeliveryDate: "2024-07-18",
	}

	recommendations, _ := client.RecommendShipDateForZipPair(params)

	fmt.Println(recommendations)
}
```

#### Java

```java
package shipments;

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

import java.util.Collections;
import java.util.HashMap;
import java.util.Map;

public class RetrieveRecommendShipDate {
    public static void main(String[] args) throws EasyPostException {
        EasyPostClient client = new EasyPostClient("EASYPOST_API_KEY");
        Map<String, Object> params = new HashMap<String, Object>();
        params.put("from_zip", "10001");
        params.put("to_zip", "10002");
        params.put("desired_delivery_date", "2024-07-18");
        params.put("carriers", Collections.singletonList("UPS"));

        RecommendShipDateForZipPairResult results = client.smartRate
                .recommendShipDate(params);

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

#### 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.SmartRate.RecommendShipDateForZipPair recommendShipDateForZipPairParameters = new()
            {
                OriginPostalCode = address1Parameters.Zip,
                DestinationPostalCode = address2Parameters.Zip,
                DesiredDeliveryDate = Fixtures.DesiredDeliveryDate,
                Carriers = ["USPS"],
            };

            EasyPost.Models.API.RecommendShipDateForZipPairResult results = await client.SmartRate.RecommendShipDate(recommendShipDateForZipPairParameters);

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

#### Node.js

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

const client = new EasyPostClient('EASYPOST_API_KEY');

(async () => {
  const results = await client.SmartRate.recommendShipDate({
    from_zip: '10001',
    to_zip: '10002',
    desired_delivery_date: '2024-07-18',
    carriers: ['UPS'],
  });

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

#### PHP

```php
<?php

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

$results = $client->smartRate->recommendShipDate([
    'from_zip' => '10001',
    'to_zip' => '10002',
    'desired_delivery_date' => '2024-07-18',
    'carriers' => ['UPS'],
]);

echo $results;
```

#### Python

```python
import easypost

client = easypost.EasyPostClient("EASYPOST_API_KEY")

results = client.smartrate.recommend_ship_date(
    from_zip="10001",
    to_zip="10002",
    desired_delivery_date="2024-07-18",
    carriers=["usps"],
)

print(results)
```

#### Ruby

```ruby
require 'easypost'

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

results = client.smart_rate.recommend_ship_date(
  from_zip: '10001',
  to_zip: '10002',
  desired_delivery_date: '2024-07-18',
  carriers: ['ups'],
)

puts results
```

The **/smartrate/deliver_on** endpoint of the Smart 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.

No shipment ID is required.

Call the **/smartrate/deliver_on** endpoint by passing the **from_zip**, **to_zip**, and an array of **carriers** along with the **desired_delivery_date**.
Receive recommendations for shipping dates that align with the delivery goals.

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

**NOTE:** Because this API does not require a shipment ID, it will only return time in transit data and no rates.