Site Logo

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:

ValueDescription
noneThis 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_sourceThis option will assign the insurance provider available with ShipEngine Carriers to the shipment (currently ParcelGuard). The response will auto-populate the insurance_provider field with parcelguard.
parcelguardThis option will assign ParcelGuard as the insurance provider for the shipment. Using this value is functionally the same as using the 'funding_source' value.
carrierThis option will add the carrier’s insurance to the package if the carrier supports it.
third_partyThis 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.
shipsuranceThis option is available to ShipEngine accounts that activated Shipsurance prior to DATE and wish to continue using the Shipsurance coverage option.

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

1
2
3
4
5
6
7
8
9
10
11
{
"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.

Request

POST v1/labels

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
POST /v1/labels HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json
{
"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
}
}
]
}
}

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.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
{
"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 what 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.
  • Carrier insurance: Follow the carrier’s claims process.

ParcelGuard Refunds for Voided Labels

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