# Insurance

An `Insurance` object represents insurance for packages purchased both via the EasyPost API as well as shipments purchased through third parties and later registered with EasyPost.
An `Insurance` object is created automatically whenever you buy a `Shipment` through EasyPost and pass insurance options during the call,or in a later call to insure a `Shipment`.

`Insurance` purchased through the `Shipment` buy or `Shipment` insure endpoints is immediately insured -
there is no possibility of rejection based on tracking information, as the package was just created.
On the other hand, `Insurance` purchased on shipments purchased outside of EasyPost requires creation with a tracking code so that EasyPost may confirm the package existence and current shipping status at the time of purchase.

Standalone insurance is created in a pending state to help distinguish it from insurance purchased for an EasyPost `Shipment`.
Both kinds of `Insurance` use the Tracking system to receive periodic updates, and will report those updates to any appropriate `Webhook` on file.
Standalone insurance will cancel itself if the tracking information for the given tracking code shows evidence of having been shipped anytime before the insurance was purchased.

Unlike a `Shipment` within EasyPost, `Insurance` objects register both a `to_address` and `from_address` according to the destination and ship-from locations of the package.
This means that a `Shipment` with its `is_return` property set to `true` actually ships to the listed `from_address`.
`Insurance` does not have a concept of `is_return`, so all insurance records refer to their true package destination as `to_address`, regardless of whether or not the shipment is a return.

---

## Insurance object

| Property | Type | Description |
|----------|------|-------------|
| id | string | Unique identifier, begins with "ins_" |
| object | string | "Insurance" |
| reference | string | The reference for this Insurance, if any |
| amount | string | USD value of insured goods with sub-cent precision |
| provider | string | The insurance provider used by EasyPost |
| provider_id | string | An identifying number for some insurance providers used by EasyPost |
| shipment_id | string | The ID of the Shipment in EasyPost, if postage was purchased via EasyPost |
| tracking_code | string | The tracking code of either the shipment within EasyPost, or provided by you during creation |
| status | string | The current status of the insurance, possible values are "new", "pending", "purchased", "failed", or "cancelled" |
| tracker | Tracker | The associated Tracker object |
| to_address | Address | The associated Address object for destination (optional) |
| from_address | Address | The associated Address object for origin (optional) |
| fee | Fee | The associated insurance Fee object if any |
| messages | Array of strings | The list of errors encountered during attempted purchase of the insurance |
| created_at | datetime | When the Insurance was created |
| updated_at | datetime | When the Insurance was last updated |

Example Object:

```json
{
  "id": "ins_e496d74110184165b0ab6c71b9ffc316",
  "object": "Insurance",
  "mode": "test",
  "reference": null,
  "status": "pending",
  "amount": "100.00000",
  "provider": "easypost",
  "provider_id": null,
  "to_address": {
    "id": "adr_ed83e5f92f6811f0a93dac1f6bc539ae",
    "object": "Address",
    "created_at": "2025-05-12T19:40:15+00:00",
    "updated_at": "2025-05-12T19:40:15+00:00",
    "name": "DR. STEVE BRULE",
    "company": null,
    "street1": "179 N HARBOR DR",
    "street2": null,
    "city": "REDONDO BEACH",
    "state": "CA",
    "zip": "90277-2506",
    "country": "US",
    "phone": "8573875756",
    "email": "DR_STEVE_BRULE@GMAIL.COM",
    "mode": "test",
    "carrier_facility": null,
    "residential": false,
    "federal_tax_id": null,
    "state_tax_id": null,
    "verifications": {
      "zip4": {
        "success": true,
        "errors": [],
        "details": null
      },
      "delivery": {
        "success": true,
        "errors": [],
        "details": {
          "latitude": 33.8436,
          "longitude": -118.39177,
          "time_zone": "America/Los_Angeles"
        }
      }
    }
  },
  "from_address": {
    "id": "adr_ed88ffb72f6811f0b5053cecef1b359e",
    "object": "Address",
    "created_at": "2025-05-12T19:40:15+00:00",
    "updated_at": "2025-05-12T19:40:15+00:00",
    "name": "EASYPOST",
    "company": null,
    "street1": "417 MONTGOMERY ST # 5",
    "street2": null,
    "city": "SAN FRANCISCO",
    "state": "CA",
    "zip": "94104-1129",
    "country": "US",
    "phone": "4153334445",
    "email": "SUPPORT@EASYPOST.COM",
    "mode": "test",
    "carrier_facility": null,
    "residential": false,
    "federal_tax_id": null,
    "state_tax_id": null,
    "verifications": {
      "zip4": {
        "success": true,
        "errors": [],
        "details": null
      },
      "delivery": {
        "success": true,
        "errors": [],
        "details": {
          "latitude": 37.79342,
          "longitude": -122.40288,
          "time_zone": "America/Los_Angeles"
        }
      }
    }
  },
  "shipment_id": null,
  "tracker": {
    "id": "trk_9135862729734d96ad2f9ed0f0565a27",
    "object": "Tracker",
    "mode": "test",
    "tracking_code": "EZ1000000001",
    "status": "pre_transit",
    "status_detail": "status_update",
    "created_at": "2025-05-09T20:40:17Z",
    "updated_at": "2025-05-09T20:40:17Z",
    "signed_by": null,
    "weight": null,
    "est_delivery_date": "2025-05-09T20:40:17Z",
    "shipment_id": null,
    "carrier": "USPS",
    "tracking_details": [
      {
        "object": "TrackingDetail",
        "message": "Pre-Shipment Info Sent to USPS",
        "description": "",
        "status": "pre_transit",
        "status_detail": "status_update",
        "datetime": "2025-04-09T20:40:17Z",
        "source": "USPS",
        "carrier_code": "",
        "tracking_location": {
          "object": "TrackingLocation",
          "city": null,
          "state": null,
          "country": null,
          "zip": null
        },
        "est_delivery_date": null
      },
      {
        "object": "TrackingDetail",
        "message": "Shipping Label Created",
        "description": "",
        "status": "pre_transit",
        "status_detail": "status_update",
        "datetime": "2025-04-10T09:17:17Z",
        "source": "USPS",
        "carrier_code": "",
        "tracking_location": {
          "object": "TrackingLocation",
          "city": "HOUSTON",
          "state": "TX",
          "country": null,
          "zip": "77063"
        },
        "est_delivery_date": null
      }
    ],
    "carrier_detail": {
      "object": "CarrierDetail",
      "service": "First-Class Package Service",
      "container_type": null,
      "est_delivery_date_local": null,
      "est_delivery_time_local": null,
      "origin_location": "HOUSTON TX, 77001",
      "origin_tracking_location": {
        "object": "TrackingLocation",
        "city": "HOUSTON",
        "state": "TX",
        "country": null,
        "zip": "77063"
      },
      "destination_location": "CHARLESTON SC, 29401",
      "destination_tracking_location": null,
      "guaranteed_delivery_date": null,
      "alternate_identifier": null,
      "initial_delivery_attempt": null
    },
    "finalized": true,
    "is_return": false,
    "public_url": "https://track.easypost.com/djE6dHJrXzkxMzU4NjI3Mjk3MzRkOTZhZDJmOWVkMGYwNTY1YTI3",
    "fees": []
  },
  "tracking_code": "EZ1000000001",
  "fee": {
    "object": "Fee",
    "type": "InsuranceFee",
    "amount": "0.50000",
    "charged": true,
    "refunded": false
  },
  "messages": [],
  "created_at": "2025-05-12T19:40:15Z",
  "updated_at": "2025-05-12T19:40:15Z"
}
```

---

## Create an Insurance

### Example: POST /insurances

#### cURL

```shell
curl -X POST https://api.easypost.com/v2/insurances \
  -u "EASYPOST_API_KEY": \
  -H 'Content-Type: application/json' \
  -d '{
    "insurance": {
      "to_address": {
        "id": "adr_..."
      },
      "from_address": {
        "id": "adr_..."
      },
      "tracking_code": "9400110898825022579493",
      "carrier": "USPS",
      "reference": "insuranceRef1",
      "amount": "100.00"
    }
  }'
```

#### Go

```go
package example

import (
	"fmt"

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

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

	toAddress, _ := client.GetAddress("adr_...")
	fromAddress, _ := client.GetAddress("adr_...")

	insurance, _ := client.CreateInsurance(
		&easypost.Insurance{
			ToAddress:    toAddress,
			FromAddress:  fromAddress,
			Reference:    "InsuranceRef1",
			Carrier:      "USPS",
			TrackingCode: "9400110898825022579493",
			Amount:       "100.00",
		},
	)

	fmt.Println(insurance)
}
```

#### Java

```java
package insurances;

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

import java.util.HashMap;

public class Create {
    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("id", "adr_...");

        HashMap<String, Object> fromAddressMap = new HashMap<String, Object>();
        fromAddressMap.put("id", "adr_...");

        HashMap<String, Object> params = new HashMap<String, Object>();
        params.put("to_address", toAddressMap);
        params.put("from_address", fromAddressMap);
        params.put("tracking_code", "9400110898825022579493");
        params.put("carrier", "USPS");
        params.put("amount", "100.00");
        params.put("reference", "InsuranceRef1");

        Insurance insurance = client.insurance.create(params);

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

#### 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.Insurance.Create parameters = new()
            {
                Amount = 100.00,
                Carrier = "USPS",
                TrackingCode = "9400110898825022579493",
                ToAddress = new EasyPost.Parameters.Address.Create
                {
                    Name = "Dr. Steve Brule",
                    Street1 = "417 Montgomery Street",
                    Street2 = "5th Floor",
                    City = "San Francisco",
                    State = "CA",
                    Country = "US",
                    Zip = "94104"
                },
                FromAddress = new EasyPost.Parameters.Address.Create
                {
                    Company = "EasyPost",
                    Street1 = "417 Montgomery Street",
                    Street2 = "Floor 5",
                    City = "San Francisco",
                    State = "CA",
                    Country = "US",
                    Zip = "94104"
                }
            };

            EasyPost.Models.API.Insurance insurance = await client.Insurance.Create(parameters);

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

#### Node.js

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

const client = new EasyPostClient('EASYPOST_API_KEY');

(async () => {
  const insurance = await client.Insurance.create({
    to_address: { id: 'adr_...' },
    from_address: { id: 'adr_...' },
    tracking_code: '9400110898825022579493',
    carrier: 'USPS',
    amount: '100.00',
    reference: 'insuranceRef1',
  });

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

#### PHP

```php
<?php

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

$insurance = $client->insurance->create([
    'to_address' => ['id' => 'adr_...'],
    'from_address' => ['id' => 'adr_...'],
    'tracking_code' => '9400110898825022579493',
    'carrier' => 'USPS',
    'amount' => '100.00',
    'reference' => 'insuranceRef1'
]);

echo $insurance;
```

#### Python

```python
import easypost

client = easypost.EasyPostClient("EASYPOST_API_KEY")

insurance = client.insurance.create(
    to_address={"id": "adr_..."},
    from_address={"id": "adr_..."},
    tracking_code="9400110898825022579493",
    carrier="USPS",
    amount="100.00",
    reference="insuranceRef1",
)

print(insurance)
```

#### Ruby

```ruby
require 'easypost'

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

insurance = client.insurance.create(
  to_address: {
    id: 'adr_...',
  },
  from_address: {
    id: 'adr_...',
  },
  tracking_code: '9400110898825022579493',
  carrier: 'USPS',
  reference: 'insuranceRef1',
  amount: '100.00',
)

puts insurance
```

An `Insurance` created via this endpoint must belong to a shipment purchased outside of EasyPost. Insurance for a `Shipment` created within EasyPost must be created via the `Shipment` buy or `Shipment` insure endpoints.
When creating Insurance for a non-EasyPost shipment, you must provide tracking_code, carrier, and amount information.

**Customers must have their own FedEx account to insure FedEx packages.**

[Note: This object is immutable after creation. Review the rendered documentation for details.]

---

## Retrieve all Insurances

### Example: GET /insurances

#### cURL

```shell
curl -X GET "https://api.easypost.com/v2/insurances?page_size=5" \
  -u "EASYPOST_API_KEY":
```

#### Go

```go
package example

import (
	"fmt"

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

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

	insurances, _ := client.ListInsurances(
		&easypost.ListOptions{
			PageSize: 5,
		},
	)

	fmt.Println(insurances)
}
```

#### Java

```java
package insurances;

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

import java.util.HashMap;

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

        HashMap<String, Object> params = new HashMap<>();
        params.put("page_size", 5);

        InsuranceCollection insurances = client.insurance.all(params);

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

#### 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.Insurance.All parameters = new()
            {
                PageSize = 5
            };

            EasyPost.Models.API.InsuranceCollection insuranceCollection = await client.Insurance.All(parameters);

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

#### Node.js

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

const client = new EasyPostClient('EASYPOST_API_KEY');

(async () => {
  const insurances = await client.Insurance.all({
    page_size: 5,
  });

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

#### PHP

```php
<?php

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

$insurances = $client->insurance->all([
    'page_size' => 5,
]);

echo $insurances;
```

#### Python

```python
import easypost

client = easypost.EasyPostClient("EASYPOST_API_KEY")

insurances = client.insurance.all(page_size=5)

print(insurances)
```

#### Ruby

```ruby
require 'easypost'

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

insurances = client.insurance.all(
  page_size: 5,
)

puts insurances
```

A list of all `Insurance` objects associated with the given `API Key` can also be retrieved. See the Pagination section of our docs for more details on retrieving all records when multiple pages are available.

---

## Retrieve an Insurance

### Example: GET /insurances/:id

#### cURL

```shell
curl -X GET https://api.easypost.com/v2/insurances/ins_... \
  -u "EASYPOST_API_KEY":
```

#### Go

```go
package example

import (
	"fmt"

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

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

	insurance, _ := client.GetInsurance("ins_...")

	fmt.Println(insurance)
}
```

#### Java

```java
package insurances;

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

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

        Insurance insurance = client.insurance.retrieve("ins_...");

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

#### 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.Insurance insurance = await client.Insurance.Retrieve("ins_...");

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

#### Node.js

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

const client = new EasyPostClient('EASYPOST_API_KEY');

(async () => {
  const insurance = await client.Insurance.retrieve('ins_...');

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

#### PHP

```php
<?php

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

$insurance = $client->insurance->retrieve('ins_...');

echo $insurance;
```

#### Python

```python
import easypost

client = easypost.EasyPostClient("EASYPOST_API_KEY")

insurance = client.insurance.retrieve("ins_...")

print(insurance)
```

#### Ruby

```ruby
require 'easypost'

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

insurance = client.insurance.retrieve('ins_...')

puts insurance
```

Retrieve an `Insurance` by its `id`.

---

## Refund an Insurance

### Example: POST /insurances/:id/refund

#### cURL

```shell
curl -X POST https://api.easypost.com/v2/insurances \
  -u "EASYPOST_API_KEY": \
  -H 'Content-Type: application/json' \
  -d '{
    "insurance": {
      "to_address": {
        "id": "adr_..."
      },
      "from_address": {
        "id": "adr_..."
      },
      "tracking_code": "9400110898825022579493",
      "carrier": "USPS",
      "reference": "insuranceRef1",
      "amount": "100.00"
    }
  }'
```

#### Go

```go
package example

import (
	"fmt"

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

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

	toAddress, _ := client.GetAddress("adr_...")
	fromAddress, _ := client.GetAddress("adr_...")

	insurance, _ := client.CreateInsurance(
		&easypost.Insurance{
			ToAddress:    toAddress,
			FromAddress:  fromAddress,
			Reference:    "InsuranceRef1",
			Carrier:      "USPS",
			TrackingCode: "9400110898825022579493",
			Amount:       "100.00",
		},
	)

	fmt.Println(insurance)
}
```

#### Java

```java
package insurances;

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

import java.util.HashMap;

public class Create {
    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("id", "adr_...");

        HashMap<String, Object> fromAddressMap = new HashMap<String, Object>();
        fromAddressMap.put("id", "adr_...");

        HashMap<String, Object> params = new HashMap<String, Object>();
        params.put("to_address", toAddressMap);
        params.put("from_address", fromAddressMap);
        params.put("tracking_code", "9400110898825022579493");
        params.put("carrier", "USPS");
        params.put("amount", "100.00");
        params.put("reference", "InsuranceRef1");

        Insurance insurance = client.insurance.create(params);

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

#### 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.Insurance.Create parameters = new()
            {
                Amount = 100.00,
                Carrier = "USPS",
                TrackingCode = "9400110898825022579493",
                ToAddress = new EasyPost.Parameters.Address.Create
                {
                    Name = "Dr. Steve Brule",
                    Street1 = "417 Montgomery Street",
                    Street2 = "5th Floor",
                    City = "San Francisco",
                    State = "CA",
                    Country = "US",
                    Zip = "94104"
                },
                FromAddress = new EasyPost.Parameters.Address.Create
                {
                    Company = "EasyPost",
                    Street1 = "417 Montgomery Street",
                    Street2 = "Floor 5",
                    City = "San Francisco",
                    State = "CA",
                    Country = "US",
                    Zip = "94104"
                }
            };

            EasyPost.Models.API.Insurance insurance = await client.Insurance.Create(parameters);

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

#### Node.js

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

const client = new EasyPostClient('EASYPOST_API_KEY');

(async () => {
  const insurance = await client.Insurance.create({
    to_address: { id: 'adr_...' },
    from_address: { id: 'adr_...' },
    tracking_code: '9400110898825022579493',
    carrier: 'USPS',
    amount: '100.00',
    reference: 'insuranceRef1',
  });

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

#### PHP

```php
<?php

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

$insurance = $client->insurance->create([
    'to_address' => ['id' => 'adr_...'],
    'from_address' => ['id' => 'adr_...'],
    'tracking_code' => '9400110898825022579493',
    'carrier' => 'USPS',
    'amount' => '100.00',
    'reference' => 'insuranceRef1'
]);

echo $insurance;
```

#### Python

```python
import easypost

client = easypost.EasyPostClient("EASYPOST_API_KEY")

insurance = client.insurance.create(
    to_address={"id": "adr_..."},
    from_address={"id": "adr_..."},
    tracking_code="9400110898825022579493",
    carrier="USPS",
    amount="100.00",
    reference="insuranceRef1",
)

print(insurance)
```

#### Ruby

```ruby
require 'easypost'

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

insurance = client.insurance.create(
  to_address: {
    id: 'adr_...',
  },
  from_address: {
    id: 'adr_...',
  },
  tracking_code: '9400110898825022579493',
  carrier: 'USPS',
  reference: 'insuranceRef1',
  amount: '100.00',
)

puts insurance
```

Refunding `Insurance` is only available for standalone insurance purchased through EasyPost. The tracking status for the insurance must be either `pre_transit`, `cancelled`, or `unknown` in order to be eligible.