# Rate

Creating a `Shipment` automatically retrieves available

`Rates`. Use the `carrier_accounts` parameter during `Shipment` creation to limit
rating to specific `CarrierAccounts`.

A `Rate` may include three pricing types:

- `rate` and `currency`: The rate available for purchase.
- `list_rate` and `list_currency`: The carrier's published, non-discounted rate.
- `retail_rate` and `retail_currency`: The carrier's retail rate.

For eligible international `Shipments`, a `Rate` may also include a `landed_cost` object with
the duties, taxes, and fees for the shipment. See the

Landed Cost Guide for eligibility and requirements.

---

## Rate object

| Property | Type | Description |
|----------|------|-------------|
| id | string | Unique, begins with 'rate_' |
| object | string | "Rate" |
| service | string | The name of the service level to use |
| carrier | string | The name of the carrier |
| carrier_account_id | string | The ID of the CarrierAccount used to generate this rate |
| shipment_id | string | ID of the Shipment this rate belongs to |
| rate | string | The actual rate quote for this service |
| currency | string | The currency for the rate |
| retail_rate | string | The retail rate is the in-store rate given with no account |
| retail_currency | string | The currency for the retail rate |
| list_rate | string | The list rate is the non-negotiated rate given for having an account with the carrier |
| list_currency | string | The currency for the list rate |
| delivery_days | integer | The delivery days for this service |
| delivery_date | string | The date for delivery |
| delivery_date_guaranteed | boolean | Indicates if delivery window is guaranteed (true) or not ( false) |
| billing_type | string | Billing type of the rate |
| landed_cost | object | Landed cost information for an eligible international Rate. See the Landed Cost Guide for eligibility and requirements |
| created_at | datetime | When the Rate was created |
| updated_at | datetime | When the Rate was last updated |

Example Object:

```json
{
  "rates": [
    {
      "id": "rate_1ad9f7990aa6453d8060325fd7f17d8a",
      "object": "Rate",
      "created_at": "2025-05-09T20:39:58Z",
      "updated_at": "2025-05-09T20:39:58Z",
      "mode": "test",
      "service": "Priority",
      "carrier": "USPS",
      "rate": "11.01",
      "currency": "USD",
      "retail_rate": "15.40",
      "retail_currency": "USD",
      "list_rate": "11.01",
      "list_currency": "USD",
      "billing_type": "easypost",
      "delivery_days": 2,
      "delivery_date": null,
      "delivery_date_guaranteed": false,
      "est_delivery_days": 2,
      "shipment_id": "shp_d121498c06864586b0c9d961e971f509",
      "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
    },
    {
      "id": "rate_997dcbfc33004ee9a80a539e1ade8b47",
      "object": "Rate",
      "created_at": "2025-05-09T20:39:58Z",
      "updated_at": "2025-05-09T20:39:58Z",
      "mode": "test",
      "service": "GroundAdvantage",
      "carrier": "USPS",
      "rate": "8.20",
      "currency": "USD",
      "retail_rate": "13.85",
      "retail_currency": "USD",
      "list_rate": "9.74",
      "list_currency": "USD",
      "billing_type": "easypost",
      "delivery_days": 3,
      "delivery_date": null,
      "delivery_date_guaranteed": false,
      "est_delivery_days": 3,
      "shipment_id": "shp_d121498c06864586b0c9d961e971f509",
      "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
    },
    {
      "id": "rate_2062b356b4574c4394d0b31d1a0d9d8f",
      "object": "Rate",
      "created_at": "2025-05-09T20:39:58Z",
      "updated_at": "2025-05-09T20:39:58Z",
      "mode": "test",
      "service": "Express",
      "carrier": "USPS",
      "rate": "51.20",
      "currency": "USD",
      "retail_rate": "59.25",
      "retail_currency": "USD",
      "list_rate": "51.20",
      "list_currency": "USD",
      "billing_type": "easypost",
      "delivery_days": 2,
      "delivery_date": null,
      "delivery_date_guaranteed": false,
      "est_delivery_days": 2,
      "shipment_id": "shp_d121498c06864586b0c9d961e971f509",
      "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
    }
  ]
}
```

---

[Content omitted: carrier services and predefined packages rendered dynamically. Review the rendered documentation for complete service level and package details.]

---

## Retrieve Rates for a Shipment

### Example: POST /beta/rates

#### cURL

```shell
$ curl -X POST https://api.easypost.com/beta/rates \
  -u "EASYPOST_API_KEY": \
  -H "Content-Type: application/json" \
  -d '{
  "shipment": {
    "to_address": {
      "name": "Dr. Steve Brule",
      "street1": "179 N Harbor Dr",
      "city": "Redondo Beach",
      "state": "CA",
      "zip": "90277",
      "country": "US",
      "phone": "8573875756",
      "email": "dr_steve_brule@gmail.com"
    },
    "from_address": {
      "name": "EasyPost",
      "street1": "417 Montgomery Street",
      "street2": "5th Floor",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94104",
      "country": "US",
      "phone": "4153334445",
      "email": "support@easypost.com"
    },
    "parcel": {
      "length": "20.2",
      "width": "10.9",
      "height": "5",
      "weight": "65.0"
    }
  }
}'
```

#### Go

```go
package example

import (
	"fmt"

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

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

	shipmentDetails := &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,
		},
	}

	rates, _ := client.BetaGetStatelessRates(shipmentDetails)

	fmt.Println(rates)
}
```

#### Java

```java
package rates;

import java.util.HashMap;
import java.util.List;

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

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

        HashMap<String, Object> toAddressMap = new HashMap<String, Object>();
        toAddressMap.put("name", "Dr. Steve Brule");
        toAddressMap.put("street1", "179 N Harbor Dr");
        toAddressMap.put("city", "Redondo Beach");
        toAddressMap.put("state", "CA");
        toAddressMap.put("country", "US");
        toAddressMap.put("phone", "8573875756");
        toAddressMap.put("email", "dr_steve_brule@gmail.com");
        toAddressMap.put("zip", "90277");

        HashMap<String, Object> fromAddressMap = new HashMap<String, Object>();
        fromAddressMap.put("name", "EasyPost");
        fromAddressMap.put("street1", "417 Montgomery Street");
        fromAddressMap.put("street2", "5th Floor");
        fromAddressMap.put("city", "San Francisco");
        fromAddressMap.put("state", "CA");
        fromAddressMap.put("zip", "94104");
        fromAddressMap.put("country", "US");
        fromAddressMap.put("phone", "4153334445");
        fromAddressMap.put("email", "support@easypost.com");

        HashMap<String, Object> parcelMap = new HashMap<String, Object>();
        parcelMap.put("length", 20.2);
        parcelMap.put("width", 10.9);
        parcelMap.put("height", 5);
        parcelMap.put("weight", 65.9);

        HashMap<String, Object> shipmentDetails = new HashMap<String, Object>();
        shipmentDetails.put("to_address", toAddressMap);
        shipmentDetails.put("from_address", fromAddressMap);
        shipmentDetails.put("parcel", parcelMap);

        List<StatelessRate> rates = client.betaRate.retrieveStatelessRates(shipmentDetails);

        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.Beta.Rate.Retrieve shipmentDetails = new()
            {
                ToAddress = new EasyPost.Parameters.Address.Create
                {
                    Name = "Dr. Steve Brule",
                    Street1 = "179 N Harbor Dr",
                    City = "Redondo Beach",
                    State = "CA",
                    Zip = "90277",
                    Country = "US",
                    Phone = "8573875756",
                    Email = "dr_steve_brule@gmail.com"
                },
                FromAddress = new EasyPost.Parameters.Address.Create
                {
                    Name = "EasyPost",
                    Street1 = "417 Montgomery Street",
                    Street2 = "5th Floor",
                    City = "San Francisco",
                    State = "CA",
                    Zip = "94104",
                    Country = "US",
                    Phone = "4153334445",
                    Email = "support@easypost.com",
                },
                Parcel = new EasyPost.Parameters.Parcel.Create
                {
                    Length = 20.2,
                    Width = 10.9,
                    Height = 5,
                    Weight = 65.9
                }
            };

            List<EasyPost.Models.API.StatelessRate> rates = await client.Beta.Rate.RetrieveStatelessRates(shipmentDetails);

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

#### Node.js

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

const client = new EasyPostClient('EASYPOST_API_KEY');

(async () => {
  const shipmentDetails = {
    to_address: {
      name: 'Dr. Steve Brule',
      street1: '179 N Harbor Dr',
      city: 'Redondo Beach',
      state: 'CA',
      zip: '90277',
      country: 'US',
      email: 'dr_steve_brule@gmail.com',
      phone: '4155559999',
    },
    from_address: {
      street1: '417 montgomery street',
      street2: 'FL 5',
      city: 'San Francisco',
      state: 'CA',
      zip: '94104',
      country: 'US',
      company: 'EasyPost',
      phone: '415-123-4567',
    },
    parcel: {
      length: 20.2,
      width: 10.9,
      height: 5,
      weight: 65.9,
    },
  };

  const rates = await client.BetaRate.retrieveStatelessRates(shipmentDetails);

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

#### PHP

```php
<?php

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

$shipmentDetails = [
    'to_address' => [
        'name' => 'Dr. Steve Brule',
        'street1' => '179 N Harbor Dr',
        'city' => 'Redondo Beach',
        'state' => 'CA',
        'zip' => '90277',
        'country' => 'US',
        'phone' => '3331114444',
        'email' => 'dr_steve_brule@gmail.com'
    ],
    'from_address' => [
        'name' => 'EasyPost',
        'street1' => '417 Montgomery Street',
        'street2' => '5th Floor',
        'city' => 'San Francisco',
        'state' => 'CA',
        'zip' => '94104',
        'country' => 'US',
        'phone' => '3331114444',
        'email' => 'support@easypost.com'
    ],
    'parcel' => [
        'length' => 20.2,
        'width' => 10.9,
        'height' => 5,
        'weight' => 65.9
    ]
];

$rates = $client->betaRate->retrieveStatelessRates($shipmentDetails);

echo $rates;
```

#### Python

```python
import easypost

client = easypost.EasyPostClient("EASYPOST_API_KEY")

shipment_details = {
    "to_address": {
        "name": "Dr. Steve Brule",
        "street1": "179 N Harbor Dr",
        "city": "Redondo Beach",
        "state": "CA",
        "zip": "90277",
        "country": "US",
        "phone": "4153334444",
        "email": "dr_steve_brule@gmail.com",
    },
    "from_address": {
        "name": "EasyPost",
        "street1": "417 Montgomery Street",
        "street2": "5th Floor",
        "city": "San Francisco",
        "state": "CA",
        "zip": "94104",
        "country": "US",
        "phone": "4153334444",
        "email": "support@easypost.com",
    },
    "parcel": {
        "length": 20.2,
        "width": 10.9,
        "height": 5,
        "weight": 65.9,
    },
}

rates = client.beta_rate.retrieve_stateless_rates(**shipment_details)

print(rates)
```

#### Ruby

```ruby
require 'easypost'

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

shipment_details = {
  to_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',
  },
  from_address: {
    name: 'EasyPost',
    street1: '417 Montgomery Street',
    street2: '5th Floor',
    city: 'San Francisco',
    state: 'CA',
    zip: '94104',
    country: 'US',
    phone: '4153334445',
    email: 'support@easypost.com',
  },
  parcel: {
    length: 20.2,
    width: 10.9,
    height: 5,
    weight: 65.9,
  },
}

rates = client.beta_rate.retrieve_stateless_rates(shipment_details)

puts rates
```

  **BETA:** This feature is in Beta and subject to change. For feedback or questions, Contact Support.

You can retrieve `Rates` without creating a `Shipment` object using this endpoint.
This endpoint is ideal when wanting to display or compare rates without creating `Shipment` objects.
The `Rate` objects returned by this endpoint do not include IDs.

---

## Regenerate Rates for a Shipment

### Example: POST /shipments/:id/rerate

#### cURL

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

#### Go

```go
package example

import (
	"fmt"

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

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

	shipment, _ := client.RerateShipment("shp_...")

	fmt.Println(shipment)
}
```

#### Java

```java
package shipments;

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

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

        Shipment shipment = client.shipment.newRates("shp_...");

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

#### 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.Models.API.Shipment shipment = await client.Shipment.RegenerateRates("shp_...");

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

#### Node.js

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

const client = new EasyPostClient('EASYPOST_API_KEY');

(async () => {
  const rates = await client.Shipment.regenerateRates('shp_...');

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

#### PHP

```php
<?php

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

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

echo $shipment;
```

#### Python

```python
import easypost

client = easypost.EasyPostClient("EASYPOST_API_KEY")

shipment = client.shipment.regenerate_rates("shp_...")

print(shipment)
```

#### Ruby

```ruby
require 'easypost'

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

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

puts shipment
```

You can regenerate the `Rates` of a `Shipment` at any time.
This is ideal when shipments aren't bought the same day as they were created and you want the most up-to-date rates available.
This operation respects the `carrier_accounts` attribute.