> ## Documentation Index
> Fetch the complete documentation index at: https://docs.goshippo.com/llms.txt
> Use this file to discover all available pages before exploring further.

<AgentInstructions>

## Submitting Feedback

If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:

POST https://docs.goshippo.com/feedback

```json
{
  "path": "/docs/Shipments/ShippingInsurance",
  "feedback": "Description of the issue"
}
```

Only submit feedback when you have something specific and actionable to report.

</AgentInstructions>

# Shipping insurance

> Add shipping insurance to your shipments through Shippo's built-in coverage or directly from FedEx, UPS, and Ontrac.

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.

<img src="https://mintcdn.com/shippo-f4b7b609/bsljvq9P8Idqx1CE/images/step1.svg?fit=max&auto=format&n=bsljvq9P8Idqx1CE&q=85&s=cf0d2ceaf4419aae89630f9f35a8c70d" alt="step 1 icon" width="44" height="32" data-path="images/step1.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.

<img src="https://mintcdn.com/shippo-f4b7b609/bsljvq9P8Idqx1CE/images/step2.svg?fit=max&auto=format&n=bsljvq9P8Idqx1CE&q=85&s=bbb481f85d226206e137bbc697adaf75" alt="step 2 icon" width="44" height="32" data-path="images/step2.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.

<Info>
  **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).
</Info>

## Insurance for single package shipments using XCover

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

<Info>
  **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.
</Info>

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.

<CodeGroup>
  ```shell cURL {% title="cURL" %} theme={null}
  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 {% title="Python" %} theme={null}
  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 {% title="PHP" %} theme={null}
  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 {% title="TypeScript" %} theme={null}
  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 {% title="Java" %} theme={null}
  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# {% title="C#" %} theme={null}
  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,
      }
  );
  ```
</CodeGroup>

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 theme={null}
{
    "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:

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

  ```Python {% title="Python" %} theme={null}
  shippo_sdk.transactions.create(
      components.TransactionCreateRequest(
          rate=shipment.rates[0].object_id,
          label_file_type=components.LabelFileTypeEnum.PDF,
          async_=False
      )
  )
  ```

  ```PHP {% title="PHP" %} theme={null}
  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 {% title="TypeScript" %} theme={null}
  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 {% title="Java" %} theme={null}
  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# {% title="C#" %} theme={null}
  Transaction transaction = await sdk.Transactions.CreateAsync(
      CreateTransactionRequestBody.CreateTransactionCreateRequest(
          new TransactionCreateRequest()
          {
              Rate = shipment.Rates[0].ObjectId,
              LabelFileType = LabelFileTypeEnum.Pdf,
              Async = false,
          }
      )
  );
  ```
</CodeGroup>

## 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.

```shell cURL theme={null}
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](/api-reference/parcels/list-all-parcels) 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 theme={null}
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.