How to Insure a Shipment

Choose your flow

Start with one question: is the label for this shipment from Easyship or another provider?

Before you start

Flow A: Shipment with an Easyship label

1. Option 1: Turn on insurance when you create the shipment (recommended)

   Add an insurance object to Create a Shipment (or Update a Shipment before the label is bought). The policy is created automatically when the label is bought, and the fee charged is the insurance_fee shown on the rate. If you leave out insured_amount, Easyship uses the total customs value of the items.

   Request bodyPOST /2024-09/shipments (excerpt)

   "insurance": { "is_insured": true, "insured_amount": 250, "insured_currency": "USD" }
2. Option 2: Add insurance after the label is bought

   Call this endpoint within 24 hours of label generation. The label must already be generated, and the shipment must not be cancelled or already insured. The request has no body.

   cURLPOST /2024-09/shipments/ESUS100000001/insure

   curl -X POST https://public-api-sandbox.easyship.com/2024-09/shipments/ESUS100000001/insure \ -H "Authorization: Bearer $EASYSHIP_TOKEN"

   Response201 Created

   { "success": { "message": "Insurance successfully purchased" } }

Flow B: Shipment with a label from another provider

1. Create a quote

   No tracking number is needed. Easyship checks the route and each product's category, then returns the fee.

   cURLPOST /2024-09/insurances/quotes

   curl -X POST https://public-api-sandbox.easyship.com/2024-09/insurances/quotes \ -H "Authorization: Bearer $EASYSHIP_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "quote": { "insured_value": 200, "currency": "USD", "origin_country": "US", "destination_country": "GB", "products": [ { "category": "Fashion", "price": 100, "quantity": 2, "description": "T-shirt" } ] } }'

   Response201 Created

   { "insurance_quote": { "quote_id": "af8f1016-6910-4f1b-b909-49a8fc48919c", "total_insurance_fee": 3.0, "insurance_fee_currency": "USD", "valid_until": "2026-10-17T12:21:00Z", "products": [{ "insured_eligibility": true, "insured_fee": 3.0 }] } }

   Field	Rule
   insured_value	Total amount to insure. Must be greater than 0, no more than the sum of price × quantity, and no more than USD 10,000 (or equivalent)
   currency	Required. ISO 4217 code, for example USD. Must be a currency Easyship supports — if it isn't, the quote fails with Currency not supported. Contact your account manager if you need a currency added
   origin_country / destination_country	ISO 3166-1 alpha-2 codes. Insurance must be available for both countries
   products[].category	Required. Use a name from List all Item Categories
   products[].price	Required. Unit price
   products[].quantity	Optional, defaults to 1
   products[].platform_product_id	Optional. If it matches a product saved in Easyship, its saved category is used

   Show total_insurance_fee to the buyer. Products in categories that can't be insured are returned with insured_eligibility: false and insured_fee: 0, and their value is left out of the cover.

2. Convert the quote into a policy

   Do this once you have a tracking number and before valid_until. A quote can be used only once.

   When you're charged. Creating the policy doesn't charge you straight away. Easyship first checks that your balance covers the fee, then creates the policy as pending (awaiting) and begins tracking the parcel. Once the first tracking update arrives — usually within a few hours — Easyship confirms whether the parcel is eligible for cover:

   • Eligible — the policy becomes active and the fee is deducted from your balance.
   • Not eligible — the policy is canceled, the quote is voided, and you are not charged.
   • Balance no longer sufficient — the policy stays awaiting and nothing is deducted. Top up your balance and the policy can still activate on a later tracking update.

   Use a tracking number the courier already recognises. If Easyship can't start tracking the parcel, both the policy and the quote are voided. Because a quote can only be used once, that quote_id can't be retried — you'll need to create a new quote and convert that one instead.

   cURLPOST /2024-09/insurances/policies-from-quote

   curl -X POST https://public-api-sandbox.easyship.com/2024-09/insurances/policies-from-quote \ -H "Authorization: Bearer $EASYSHIP_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "policy": { "quote_id": "af8f1016-6910-4f1b-b909-49a8fc48919c", "tracking_number": "1Z999AA10123456784", "courier_service_name": "DHL Express Worldwide", "policy_holder_type": "merchant", "email_address": "[email protected]", "first_name": "John", "last_name": "Doe" } }'

   Response201 Created

   { "insurance_policy": { "policy_id": "IPUS10000103", "insured_value": 200.0, "insurance_fee": 3.0, "currency": "USD", "tracking_number": "1Z999AA10123456784", "status": "Policy Created Successfully" } }

   Field	Rule
   quote_id, tracking_number, email_address, first_name, last_name	Required
   courier_service_name	Required. Must be one of the courier names listed in the API reference, for example, DHL Express Worldwide
   policy_holder_type	merchant (default) or buyer
   Optional	order_number, order_date, ship_date, phone, send_email, shipping and billing address fields

   Where to find these policies. Quote-based policies don't appear on the Easyship dashboard. Once a policy is active, Easyship emails the policyholder a link to the claims portal, where they can file claims.

List and cancel policies

FAQ and common errors

Related