# Shipping insurance

You can use the Shippo API  to add insurance to your shipments programmatically. Shipping insurance helps you avoid losing money on lost or stolen packages.
The Shippo API supports two methods for purchasing insurance for your shipment.

![step 1 icon](/assets/step1.14ee6260337a0b326de06f1173e3703f933b52790e666cd390788635d3e7e0a6.9c1bb791.svg) You can purchase insurance using our [built-in insurance service](#insurance-for-single-package-shipments-using-xcover) powered by [XCover](https://www.xcover.com/en-us/help/partners/shippo). This is available for **ALL** of our carriers.

![step 2 icon](/assets/step2.37831ee18f1f0290fe49fb6b512319f7a374b18f4063f0302fe35b4afcd9816b.9c1bb791.svg) You can purchase insurance [directly from carriers](#insurance-for-single-package-shipments-using-carrier-insurance) that provide their own insurance option (FedEx, UPS, and Ontrac).

We recommend using Shippo's built-in insurance because it offers a more comprehensive coverage at a lower price.

note
To learn more about how XCover works with Shippo, see our [XCover help article](https://support.goshippo.com/hc/en-us/articles/18146261565083-Introducing-New-Enhanced-Shipping-Insurance-with-XCover#introducing-new-enhanced-shipping-insurance-with-xcover-0-0).

## Insurance for single package shipments using XCover

For shipments consisting of only one package, you can specify insurance directly from the Shipment object.

note
It's important to review the XCover coverage details.

* For details on shipments originating from the US, refer to [this guide on shipping protection](https://www.xcover.com/en-us/pds/shipping-protection-shippo-us?utm_source=xcms&utm_medium=pds&utm_campaign=parcel_insurance_v1).
* For details on shipments originating from outside of the US (CA, UK, France, Spain, Italy, Netherlands, Germany), refer to [this guide on shipping protection](https://www.xcover.com/en-us/pds/shipping-protection-shippo-ca?utm_source=xcms&utm_medium=pds&utm_campaign=parcel_insurance_v1).


XCover provides insurance for shipments and parcels up to an `amount` of $10,000 USD. Depending the source country, this limit can vary.

For shipments originating from the US, XCover has a 25% deductible for Jewelry/Watches, Antiques/Artwork, and Glassware/Ceramics.

Make sure to specify the `amount` and `currency`, as well as `content` within the `insurance` attribute inside ShipmentExtras attribute. The `provider` will default to Shippo's insurance provider.


``` cURL
curl https://api.goshippo.com/shipments/\
    -H "Authorization: ShippoToken <API_Token>"\
    -d address_from="d799c2679e644279b59fe661ac8fa488"\
    -d address_to="42236bcf36214f62bcc6d7f12f02a849"\
    -d parcels=["7df2ecf8b4224763ab7c71fae7ec8274"]\
    -d extra='{"insurance": {"amount": "200", "currency": "USD", "content": "t-shirts" }}'\
    -d async=false
```


```Python Python
import shippo
from shippo.models import components

shippo_sdk = shippo.Shippo(api_key_header="<API_Token>")

address_from = components.AddressCreateRequest(
    name="Shawn Ippotle",
    street1="215 Clayton St.",
    city="San Francisco",
    state="CA",
    zip="94117",
    country="US",
    phone="+1 555 341 9393",
    email="shippotle@shippo.com"
)

address_to = components.AddressCreateRequest(
    name="Mr Hippo",
    street1="Broadway 1",
    city="New York",
    state="NY",
    zip="10007",
    country="US",
    phone="+1 555 341 9393",
    email="mrhippo@shippo.com"
)

parcel = components.ParcelCreateRequest(
    length="5",
    width="5",
    height="5",
    distance_unit=components.DistanceUnitEnum.IN,
    weight="2",
    mass_unit=components.WeightUnitEnum.LB
)

insurance = components.Insurance(
    amount="200",
    currency="USD",
    content="t-shirts"
)

shipment = shippo_sdk.shipments.create(
    components.ShipmentCreateRequest(
        address_from=address_from,
        address_to=address_to,
        parcels=[parcel],
        extra=components.ShipmentExtra(
            insurance=insurance
        )
    )
)
```


```PHP PHP
require_once('lib/Shippo.php');
Shippo::setApiKey("<API_Token>");

$fromAddress = array(
    'name' => 'Shawn Ippotle',
    'street1' => '215 Clayton St.',
    'city' => 'San Francisco',
    'state' => 'CA',
    'zip' => '94117',
    'country' => 'US',
    'phone' => '+1 555 341 9393',
    'email' => 'shippotle@shippo.com'
);

$toAddress = array(
    'name' => 'Mr Hippo"',
    'street1' => 'Broadway 1',
    'city' => 'New York',
    'state' => 'NY',
    'zip' => '10007',
    'country' => 'US',
    'phone' => '+1 555 341 9393',
    'email' => 'mrhippo@shippo.com'
);

$parcel = array(
    'length'=> '5',
    'width'=> '5',
    'height'=> '5',
    'distance_unit'=> 'in',
    'weight'=> '2',
    'mass_unit'=> 'lb',
);

$insurance = array(
    'amount' => '200',
    'currency' => 'USD',
    'content' => 't-shirts'
);

$shipment = Shippo_Shipment::create(
    array(
        "address_from" => $fromAddress,
        "address_to" => $toAddress,
        "parcels" => array($parcel),
        "async" => false,
        "extra" => array("insurance" => $insurance)
    )
);
```


```typescript TypeScript
const shippo = new Shippo({apiKeyHeader: '<API_Token>'});

const addressFrom: AddressCreateRequest = {
    name: "Shawn Ippotle",
    street1: "215 Clayton St.",
    city: "San Francisco",
    state: "CA",
    zip: "94117",
    country: "US",
    phone: "+1 555 341 9393",
    email: "shippotle@shippo.com"
};

const addressTo: AddressCreateRequest = {
    name: "Mr Hippo",
    street1: "Broadway 1",
    city: "New York",
    state: "NY",
    zip: "10007",
    country: "US",
    phone: "+1 555 341 9393",
    email: "mrhippo@shippo.com"
};

const parcel: ParcelCreateRequest = {
    length: "5",
    width: "5",
    height: "5",
    distanceUnit: DistanceUnitEnum.In,
    weight: "2",
    massUnit: WeightUnitEnum.Lb
};

const insurance: Insurance = {
    amount: "200",
    currency: "USD",
    content: "t-shirts"
};

const shipment = await shippo.shipments.create({
    addressFrom: addressFrom,
    addressTo: addressTo,
    parcels: [parcel],
    async: true,
    extra: { insurance: insurance }
});
```


```Java Java
Shippo.setApiKey('<API_Token>');

// To Address
HashMap<String, Object> addressToMap = new HashMap<String, Object>();
addressToMap.put("name", "Mr Hippo");
addressToMap.put("company", "Shippo");
addressToMap.put("street1", "215 Clayton St.");
addressToMap.put("city", "San Francisco");
addressToMap.put("state", "CA");
addressToMap.put("zip", "94117");
addressToMap.put("country", "US");
addressToMap.put("phone", "+1 555 341 9393");
addressToMap.put("email", "mrhippo@goshipppo.com");

// From Address
HashMap<String, Object> addressFromMap = new HashMap<String, Object>();
addressFromMap.put("name", "Ms Hippo");
addressFromMap.put("company", "San Diego Zoo");
addressFromMap.put("street1", "2920 Zoo Drive");
addressFromMap.put("city", "San Diego");
addressFromMap.put("state", "CA");
addressFromMap.put("zip", "92101");
addressFromMap.put("country", "US");
addressFromMap.put("email", "mshippo@goshipppo.com");
addressFromMap.put("phone", "+1 619 231 1515");
addressFromMap.put("metadata", "Customer ID 123456");

// Parcel
HashMap<String, Object> parcelMap = new HashMap<String, Object>();
parcelMap.put("length", "5");
parcelMap.put("width", "5");
parcelMap.put("height", "5");
parcelMap.put("distance_unit", "in");
parcelMap.put("weight", "2");
parcelMap.put("mass_unit", "lb");

// Insurance
HashMap<String, Object> insuranceMap = new HashMap<String, Object>();
insuranceMap.put("amount", "200");
insuranceMap.put("currency", "USD");
insuranceMap.put("content", "t_shirts");

// Extra
HashMap<String, Object> extraMap = new HashMap<String, Object>();
extraMap.put("insurance", insuranceMap);

// Shipment
HashMap<String, Object> shipmentMap = new HashMap<String, Object>();
shipmentMap.put("address_to", addressToMap);
shipmentMap.put("address_from", addressFromMap);
shipmentMap.put("parcels", parcelMap);
shipmentMap.put("extra", extraMap);
shipmentMap.put("async", false);

Shipment shipment = Shipment.create(shipmentMap);
```


```cs C#
using Shippo;
using Shippo.Models.Components;
ShippoSDK sdk = new ShippoSDK(apiKeyHeader: "<API_Token>");
AddressFrom addressFrom = AddressFrom.CreateAddressCreateRequest(
    new AddressCreateRequest()
    {
        Name = "Shawn Ippotle",
        Street1 = "215 Clayton St.",
        City = "San Francisco",
        State = "CA",
        Zip = "94117",
        Country = "US",
        Phone = "+1 555 341 9393",
        Email = "shippotle@shippo.com",
    }
);
AddressTo addressTo = AddressTo.CreateAddressCreateRequest(
    new AddressCreateRequest()
    {
        Name = "Mr Hippo",
        Street1 = "Broadway 1",
        City = "New York",
        State = "NY",
        Zip = "10007",
        Country = "US",
        Phone = "+1 555 341 9393",
        Email = "mrhippo@shippo.com",
    }
);
Shippo.Models.Components.Parcels parcel = Shippo.Models.Components.Parcels.CreateParcelCreateRequest(
    new ParcelCreateRequest()
    {
        Length = "5",
        Width = "5",
        Height = "5",
        DistanceUnit = DistanceUnitEnum.In,
        Weight = "2",
        MassUnit = WeightUnitEnum.Lb,
    }
);
Insurance insurance = new Insurance()
{
    Amount = "200",
    Currency = "USD",
    Content = "t-shirts",
};
Shipment shipment = await sdk.Shipments.CreateAsync(
    new ShipmentCreateRequest()
    {
        AddressFrom = addressFrom,
        AddressTo = addressTo,
        Parcels = new List<Shippo.Models.Components.Parcels>() { parcel },
        Extra = new ShipmentExtra()
        {
            Insurance = insurance,
        },
        Async = false,
    }
);
```

Each valid Shipment object request will trigger a number of Rate objects that contain the shipment insurance information.
The field `included_insurance_price` indicates the insurance fee for the requested coverage. That fee is also included in the rate "amount" as well.


```json
{
    "status": "SUCCESS",
    "object_created": "2013-12-01T06:24:20.121Z",
    "object_updated": "2013-12-01T06:24:20.121Z",
    "object_id": "5e40ead7cffe4cc1ad45108696162e42",
    "object_owner": "shippotle@shippo.com",
    "address_from": {
        "object_id": "0943ae4e373e4120a99c337e496dcce8",
        "validation_results": {},
        "is_complete": true,
        "company": "",
        "street_no": "",
        "name": "Mr. Hippo",
        "street1": "215 Clayton St.",
        "street2": "",
        "city": "San Francisco",
        "state": "CA",
        "zip": "94117",
        "country": "US",
        "phone": "+15553419393",
        "email": "support@shippo.com",
        "is_residential": null
    },
    "address_to": {
        "object_id": "4c7185d353764d0985a6a7825aed8ffb",
        "validation_results": {},
        "is_complete": true,
        "name":"Mrs. Hippo",
        "street1":"965 Mission St.",
        "city":"San Francisco",
        "state":"CA",
        "zip":"94105",
        "country":"US",
        "phone":"+1 555 341 9393",
        "email":"support@shippo.com",
        "is_residential": false
    },
    "address_return": {
        "object_id": "0943ae4e373e4120a99c337e496dcce8",
        "validation_results": {},
        "is_complete": true,
        "company": "",
        "street_no": "",
        "name": "Mr. Hippo",
        "street1": "215 Clayton St.",
        "street2": "",
        "city": "San Francisco",
        "state": "CA",
        "zip": "94117",
        "country": "US",
        "phone": "+15553419393",
        "email": "support@shippo.com",
        "is_residential": null
    },
    "parcels": [{
        "object_id": "ec952343dd4843c39b42aca620471fd5",
        "object_created": "2013-12-01T06:24:21.121Z",
        "object_updated": "2013-12-01T06:24:21.121Z",
        "object_owner": "shippotle@shippo.com",
        "template": null,
        "length":"5",
        "width":"5",
        "height":"5",
        "distance_unit":"in",
        "weight":"2",
        "mass_unit":"lb",
        "value_amount": null,
        "value_currency": null,
        "metadata": "",
        "line_items": [],
        "test": true
    }],
    "shipment_date": "2013-12-03T12:00:00.000Z",
    "extra": {
        "insurance": {
            "amount": "200",
            "currency": "USD",
            "content": "t-shirts"
        },
        "reference_1": "",
        "reference_2": ""
    },
    "customs_declaration": "",
    "rates": [
        {
            "object_created": "2013-12-01T06:24:21.121Z",
            "object_id": "545ab0a1a6ea4c9f9adb2512a57d6d8b",
            "object_owner": "shippotle@shippo.com",
            "shipment": "5e40ead7cffe4cc1ad45108696162e42",
            "attributes": [],
            "amount": "5.50",
            "currency": "USD",
            "amount_local": "5.50",
            "currency_local": "USD",
            "included_insurance_price": "1.05",
            "provider": "USPS",
            "provider_image_75": "https://cdn2.goshippo.com/providers/75/USPS.png",
            "provider_image_200": "https://cdn2.goshippo.com/providers/200/USPS.png",
            "servicelevel": {
                "name": "Priority Mail",
                "token": "usps_priority",
                "terms": "",
                "extended_token": "usps_priority",
                "parent_servicelevel": null
            },
            "estimated_days": 2,
            "arrives_by": null,
            "duration_terms": "Delivery in 1 to 3 business days.",
            "messages": [],
            "carrier_account": "078870331023437cb917f5187429b093",
            "test": false,
            "zone": "20"
        },
        ...
    ],
    "carrier_accounts": [],
    "metadata": "Customer ID 123456",
    "messages": [],
    "test": false
}
```

You can then create the shipping label by POSTing to the Transaction endpoint as usual:


```shell cURL
curl https://api.goshippo.com/transactions\
    -H "Authorization: ShippoToken <API_Token>"\
    -d rate="cf6fea899f1848b494d9568e8266e076"
    -d label_file_type="PDF"
    -d async=false
```


```Python Python
shippo_sdk.transactions.create(
    components.TransactionCreateRequest(
        rate=shipment.rates[0].object_id,
        label_file_type=components.LabelFileTypeEnum.PDF,
        async_=False
    )
)
```


```PHP PHP
require_once('lib/Shippo.php');
Shippo::setApiKey("<API_Token>");

$fromAddress = array(
    'name' => 'Shawn Ippotle',
    'street1' => '215 Clayton St.',
    'city' => 'San Francisco',
    'state' => 'CA',
    'zip' => '94117',
    'country' => 'US',
    'phone' => '+1 555 341 9393',
    'email' => 'shippotle@shippo.com'
);

$toAddress = array(
    'name' => 'Mr Hippo"',
    'street1' => 'Broadway 1',
    'city' => 'New York',
    'state' => 'NY',
    'zip' => '10007',
    'country' => 'US',
    'phone' => '+1 555 341 9393',
    'email' => 'mrhippo@shippo.com'
);

$parcel = array(
    'length'=> '5',
    'width'=> '5',
    'height'=> '5',
    'distance_unit'=> 'in',
    'weight'=> '2',
    'mass_unit'=> 'lb',
);

$insurance = array(
    'amount' => '200',
    'currency' => 'USD',
    'content' => 't-shirts'
);

$shipment = Shippo_Shipment::create(
    array(
        "address_from" => $fromAddress,
        "address_to" => $toAddress,
        "parcels" => array($parcel),
        "async" => false,
        "extra" => array("insurance" => $insurance)
    )
);
```


```typescript TypeScript
const shippo = new Shippo({apiKeyHeader: '<API_Token>'});

const addressFrom: AddressCreateRequest = {
    name: "Shawn Ippotle",
    street1: "215 Clayton St.",
    city: "San Francisco",
    state: "CA",
    zip: "94117",
    country: "US",
    phone: "+1 555 341 9393",
    email: "shippotle@shippo.com"
};

const addressTo: AddressCreateRequest = {
    name: "Mr Hippo",
    street1: "Broadway 1",
    city: "New York",
    state: "NY",
    zip: "10007",
    country: "US",
    phone: "+1 555 341 9393",
    email: "mrhippo@shippo.com"
};

const parcel: ParcelCreateRequest = {
    length: "5",
    width: "5",
    height: "5",
    distanceUnit: DistanceUnitEnum.In,
    weight: "2",
    massUnit: WeightUnitEnum.Lb
};

const insurance: Insurance = {
    amount: "200",
    currency: "USD",
    content: "t-shirts"
};

const shipment = await shippo.shipments.create({
    addressFrom: addressFrom,
    addressTo: addressTo,
    parcels: [parcel],
    async: true,
    extra: { insurance: insurance }
});
```


```Java Java
Shippo.setApiKey('<API_Token>');

// To Address
HashMap<String, Object> addressToMap = new HashMap<String, Object>();
addressToMap.put("name", "Mr Hippo");
addressToMap.put("company", "Shippo");
addressToMap.put("street1", "215 Clayton St.");
addressToMap.put("city", "San Francisco");
addressToMap.put("state", "CA");
addressToMap.put("zip", "94117");
addressToMap.put("country", "US");
addressToMap.put("phone", "+1 555 341 9393");
addressToMap.put("email", "mrhippo@goshipppo.com");

// From Address
HashMap<String, Object> addressFromMap = new HashMap<String, Object>();
addressFromMap.put("name", "Ms Hippo");
addressFromMap.put("company", "San Diego Zoo");
addressFromMap.put("street1", "2920 Zoo Drive");
addressFromMap.put("city", "San Diego");
addressFromMap.put("state", "CA");
addressFromMap.put("zip", "92101");
addressFromMap.put("country", "US");
addressFromMap.put("email", "mshippo@goshipppo.com");
addressFromMap.put("phone", "+1 619 231 1515");
addressFromMap.put("metadata", "Customer ID 123456");

// Parcel
HashMap<String, Object> parcelMap = new HashMap<String, Object>();
parcelMap.put("length", "5");
parcelMap.put("width", "5");
parcelMap.put("height", "5");
parcelMap.put("distance_unit", "in");
parcelMap.put("weight", "2");
parcelMap.put("mass_unit", "lb");

// Insurance
HashMap<String, Object> insuranceMap = new HashMap<String, Object>();
insuranceMap.put("amount", "200");
insuranceMap.put("currency", "USD");
insuranceMap.put("content", "t_shirts");

// Extra
HashMap<String, Object> extraMap = new HashMap<String, Object>();
extraMap.put("insurance", insuranceMap);

// Shipment
HashMap<String, Object> shipmentMap = new HashMap<String, Object>();
shipmentMap.put("address_to", addressToMap);
shipmentMap.put("address_from", addressFromMap);
shipmentMap.put("parcels", parcelMap);
shipmentMap.put("extra", extraMap);
shipmentMap.put("async", false);

Shipment shipment = Shipment.create(shipmentMap);
```


```cs C#
Transaction transaction = await sdk.Transactions.CreateAsync(
    CreateTransactionRequestBody.CreateTransactionCreateRequest(
        new TransactionCreateRequest()
        {
            Rate = shipment.Rates[0].ObjectId,
            LabelFileType = LabelFileTypeEnum.Pdf,
            Async = false,
        }
    )
);
```

## Insurance for single package shipments using carrier insurance

You can purchase insurance directly from a carrier by specifying your `provider` within the `insurance` attribute inside ShipmentExtras attribute. This is available only for FedEx, UPS, and Ontrac.


```
curl https://api.goshippo.com/shipments/\
    -H "Authorization: ShippoToken <API_Token>"\
    -d address_from="d799c2679e644279b59fe661ac8fa488"\
    -d address_to="42236bcf36214f62bcc6d7f12f02a849"\
    -d parcels=["7df2ecf8b4224763ab7c71fae7ec8274"]\
    -d extra='{"insurance": {"amount": "200", "currency": "USD", "content": "t-shirts", "provider":"FEDEX" }}'\
    -d async=false
```

## Insurance for multi-piece shipments

For multi-piece shipments you can choose to purchase specific insurance amounts for each package. This can be done through the [extras](/shippoapi/public-api/parcels/parcelextra) attribute when creating your Parcel object within the Shipment request.

The following example shows a request to add insurance to each parcel in a multi-piece shipment using carrier provided insurance.
To add insurance using XCover, omit `provider` from your request.


```shell
curl https://api.goshippo.com/shipment/\
-H "Authorization: ShippoToken <API_Token>"\
-H "Content-Type: application/json"\
-d '{
    "address_from": "d799c2679e644279b59fe661ac8fa488",
    "address_to": "42236bcf36214f62bcc6d7f12f02a849",
    "parcels": [
        {
            "length": "5",
            "width": "5",
            "height": "5",
            "distance_unit": "cm",
            "weight": "2",
            "mass_unit": "lb",
            "template": "",
            "metadata": "Box1",
            "extra": {
                "insurance": {
                    "amount": 25.00,
                    "currency": "USD",
                    "provider": "FEDEX"
                    }
            }
        },
        {
            "length": "5",
            "width": "10",
            "height": "15",
            "distance_unit": "cm",
            "weight": "6",
            "mass_unit": "lb",
            "template": "",
            "metadata": "Box2",
            "extra": {
                "insurance": {
                    "amount": 50.00,
                    "currency": "USD",
                    "provider": "FEDEX"
                    }
            }
        },
        {
            "length": "2",
            "width": "8",
            "height": "9",
            "distance_unit": "cm",
            "weight": "5",
            "mass_unit": "lb",
            "template": "",
            "metadata": "Box3",
            "extra": {
                "insurance": {
                    "amount": 45.00,
                    "currency": "USD",
                    "provider": "FEDEX"
                    }
            }
        }
    ],
    "async": false
}
```

## Handling shipment-level and parcel-level insurance

If both shipment-level and parcel-level insurance are specified, the parcel-level insurance will take precedence. Parcels without parcel-level insurance will have the shipment-level insurance amount applied to that parcel.

If only shipment-level insurance is specified, then the shipment insurance amount will be applied to each parcel and not divided amongst parcels.

## Canceling or refunding insurance

Please see our page on [Refunds](/docs/billing_and_invoices/refundinglabels) for more info on refunding insured shipments.