shipengine-logo

Parcel Insurance

Enable Shipsurance

Shipsurance is included by default, you just need to enable it! Here are the steps to do so!

  1. Log into the ShipEngine Portal.
  2. Select Carrier Management.
  3. Select the Insurance tab.
  4. Toggle 3rd Party Insurance to on and follow the on-screen instructions.
Insurance Dashboard

Adding Insurance Funds

You may need to auto fund your account from time to time. For example, if you don't normally ship items over $100, and may want to add funds to insurance rather than keeping the account funded.

PATCH /v1/insurance/shipsurance/add_funds

Example Request

1
2
3
4
5
6
7
8
9
PATCH /v1/insurance/shipsurance/add_funds HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json


{
  "currency": "usd",
  "amount": 10.0
}

Example Response

Shipengine responds with an object showing the new balance in your account.

1
2
3
4
5
6
{
  "balance": {
    "currency": "usd",
    "amount": 50.00
  }
}

Check Your Insurance Balance

GET /v1/insurance/shipsurance/balance

Example Request

1
2
GET /v1/insurance/shipsurance/balance HTTP/1.1
Host: app.shipengine.com

Example Response

1
2
3
4
5
6
{
  "balance": {
    "currency": "usd",
    "amount": 50.00
  }
}

Adding Insurance to a Shipment

When creating a label, you can declare the package value to ensure reimbursement if the package is lost or damaged in the mail stream. Start by setting the insurance_provider field to one of the following values:

Insurance ProviderDescription
none (default)The package will not be insured. Some carriers may still offer reimbursement up to a certain value.
shipsurancePurchase insurance from Shipsurance. You need to setup your billing info first.
carrierGet increased reimbursement coverage from the carrier based on the declared value of the package.
third_partyThe package is insured by a third-party insurance service, outside of ShipEngine.

In addition to the insurance_provider field, 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": "shipsurance",
  "packages": [
    {
      "insured_value": {
        "currency": "usd",
        "amount": 200
      }
    }
  ]
}

Example Request

This is an example of a full request to create a label for a shipment that is insured.

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": "shipsurance",
    "packages": [
      {
        "weight": {
          "value": 1,
          "unit": "ounce"
        },
        "insured_value": {
          "currency": "usd",
          "amount": 200
        }
      }
    ]
  }
}

Example Response

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
{
    "label_id": "se-test-41817394",
    "status": "processing",
    "shipment_id": "se-41817394",
    "ship_date": "2017-04-03T00:00:00Z",
    "created_at": "2017-04-03T17:30:19.9541821Z",
    "shipment_cost": {
    "currency": "usd",
    "amount": 0.0
    },
    "insurance_cost": {
    "currency": "usd",
    "amount": 0.0
    },
    "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"
    }
}