Parcel Insurance

tip

Setup Billing First

To setup 3rd-party shipping insurance, you must add billing information to your account.
Go to Billing

Enable Shipsurance

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

Log into the ShipEngine Portal.
Select Carrier Management.
Select the Insurance tab.
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.

Warning

This request costs money!

There is no test mode for adding funds to insurance, you will be charged.

PATCH /v1/insurance/shipsurance/add_funds

curl -iX PATCH https://api.shipengine.com/v1/insurance/shipsurance/add_funds \
-H 'Content-Type: application/json' \
-H 'API-Key: __YOUR_API_KEY_HERE__' \
-d '
{
  "currency": "usd",
  "amount": 10.0
}'

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

{
  "balance": {
    "currency": "usd",
    "amount": 50.00
  }
}

Tip

Auto Funding

We recommend that you auto fund your insurance account. By auto funding, you won't receive insufficient balance alerts. You can auto fund for as little as $10 when it falls below the minimum.

Check Your Insurance Balance

GET /v1/insurance/shipsurance/balance

Example Request

curl -iX GET https://api.shipengine.com/v1/insurance/shipsurance/balance \
-H 'Content-Type: application/json' \
-H 'API-Key: __YOUR_API_KEY_HERE__'

Example Response

{
  "balance": {
    "currency": "usd",
    "amount": 50.00
  }
}

Adding Insurance to a Shipment

When creating a label, you can choose to purchase insurance for the package by setting the insurance_provider field. It can be set to any of the following values:

Insurance Provider	Description
`none` (default)	The package will not be insured
`shipsurance`	Purchase insurance from Shipsurance. You need to setup your billing info first.
`carrier`	Purchase insurance from the carrier.
`third_party`	The package is insured by a third-party insurance service, outside of ShipEngine.

POST /v1/labels

In addition to the insurance_provider field, you will also need to set the insured_value of each package in the shipment. For example:

{
  "insurance_provider": "shipsurance",
  "packages": [
  {
    "insured_value": {
      "currency": "usd",
      "amount": 200.0
    }
  }]
}

Example Request

curl -iX POST https://api.shipengine.com/v1/labels \
-H 'Content-Type: application/json' \
-H 'API-Key: __YOUR_API_KEY_HERE__' \
-d '
{
  "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.0,
          "unit": "ounce"
        },
        "insured_value": {
          "currency": "usd",
          "amount": 200.0
        }
      }
    ]
  }
}'

Example Response

{
  "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"
  }
}