Add Insurance to Shipments | ShipEngine

🎉ShipEngine is becoming ShipStation API🎉

Over the next few months you'll notice the ShipEngine website, documentation portal, and dashboard being rebranded as ShipStation API. For our ShipEngine customers, you don't need to take any action or change any of your integrations in any way. All endpoints will remain the same and continue to function as they always have.

To learn more about what's coming, review our New ShipStation API page.

Add Insurance to Shipments

You can add insurance to a shipment when getting a rate, creating a shipment, or purchasing a label. You’ll set the insurance_provider property at the shipment level and the insured_value property at the package level (for multipackage shipments, you’ll need to do this for every package in the shipment).

Supported values for the insurance_provider property:

Value	Description
`none`	This is the default value for this property and means the package will not be insured. Does not affect reimbursement from carriers that provide default coverage.
`funding_source`	This option will assign the insurance provider available with ShipStation Carriers to the shipment (currently ParcelGuard, available for US-based accounts only). The response will auto-populate the `insurance_provider` field with `parcelguard`.
`parcelguard`	This option will assign ParcelGuard as the insurance provider for the shipment. Using this value is functionally the same as using the 'funding_source' value. Currently available for US-based accounts only.
`carrier`	This option will add the carrier’s insurance to the package if the carrier supports it.
`third_party`	This option allows you to indicate the package is insured by a third-party insurance service. Using this value does not add insurance to a shipment. Use this option if you have your own parcel insurance account and wish to identify packages insured externally for reporting purposes.
`shipsurance`	This option is available to US-based ShipStation API accounts that activated Shipsurance prior to July 10, 2024 and wish to continue using the Shipsurance coverage option.
`x_cover`	This option will assign XCover from Cover Genius as the insurance provider for the shipment. Currently available for UK-based accounts only.

If the insurance_provider property is set to anything other than none, you will also need to set the insured_value of each package in the shipment. For example:

{
  "insurance_provider": "funding_source",
  "packages": [
    {
      "insured_value": {
        "currency": "usd",
        "amount": 200
      }
    }
  ]
}

Example Request & Response

This is an example of a purchase label request for a shipment insured with ParcelGuard.

POST v1/labels

POST /v1/labels HTTP/1.1

{
  "shipment": {
    "service_code": "usps_priority_mail",
    "ship_to": {
      "name": "Amanda Miller",
      "phone": "555-555-5555",
      "address_line1": "525 S Winchester Blvd",
      "city_locality": "San Jose",
      "state_province": "CA",
      "postal_code": "95128",
      "country_code": "US",
      "address_residential_indicator": "yes"
    },
    "ship_from": {
      "company_name": "Example Corp.",
      "name": "John Doe",
      "phone": "111-111-1111",
      "address_line1": "4009 Marathon Blvd",
      "address_line2": "Suite 300",
      "city_locality": "Austin",
      "state_province": "TX",
      "postal_code": "78756",
      "country_code": "US",
      "address_residential_indicator": "no"
    },
    "confirmation": "none",
    "insurance_provider": "funding_source",
    "packages": [
      {
        "weight": {
          "value": 1,
          "unit": "ounce"
        },
        "insured_value": {
          "currency": "usd",
          "amount": 200
        }
      }
    ]
  }
}

Example Response

The response will include the insurance_cost property that shows the insurance fee (add to the shipment_cost amount for the total cost of the label including insurance) and the URL to use if you need to file an insurance claim.

{
    "label_id": "se-test-41817394",
    "status": "processing",
    "shipment_id": "se-41817394",
    "ship_date": "2024-04-03T00:00:00Z",
    "created_at": "2024-04-03T17:30:19.9541821Z",
    "shipment_cost":
      {
       "currency": "usd",
        "amount": 9.89
      },
    "insurance_cost":
      {
        "currency": "usd",
        "amount": 2.18
      },
    "tracking_number": "9999999999999",
    "is_return_label": false,
    "is_international": false,
    "batch_id": "",
    "carrier_id": "se-0",
    "service_code": "usps_priority_mail",
    "package_code": "package",
    "voided": false,
    "voided_at": null,
    "label_format": "pdf",
    "label_layout": "4x6",
    "trackable": true,
    "carrier_code": "stamps_com",
    "tracking_status": "unknown",
    "label_download":
      {
        "pdf": "https://api.shipengine.com/v1/downloads/1/s_Tqsu9euEKub6Acc_9UIg/testlabel-2128732.pdf",
        "png": "https://api.shipengine.com/v1/downloads/1/s_Tqsu9euEKub6Acc_9UIg/testlabel-2128732.png",
        "zpl": "https://api.shipengine.com/v1/downloads/1/s_Tqsu9euEKub6Acc_9UIg/testlabel-2128732.zpl",
        "href": "https://api.shipengine.com/v1/downloads/1/s_Tqsu9euEKub6Acc_9UIg/testlabel-2128732.pdf"
      },
    "form_download": null,
    "insurance_claim":
      {
        "href": "https://www.dsiins.com/extclaims/Default.asp?cid=shipengine&psid=0&shipmentid=0"
      }
}

Filing a Claim

How you file a claim will depend on the type of insurance you added to the shipment.

ParcelGuard: Go to the link provided in the shipment response insurance_claim field and follow the on-screen instructions. By following the link from the response, most of the claim fields will be auto-filled with the required shipment details.
XCover: Go to the link provided in the shipment response insurance_claim field and follow the on-screen instructions.
Carrier insurance: Follow the carrier’s claims process.

ParcelGuard and XCover Refunds for Voided Labels

If you void a label for a shipment that includes ParcelGuard or XCover, the insurance cost will be immediately refunded back to your account balance.