Parcel Insurance

Adding insurance to your shipments ensures you are financially protected against loss or damage that could occur while the shipment is in transit. While some carriers provide default loss/damage coverage, if you need to cover a shipment valued more than the default amount or your carrier provides no default coverage at all, ShipStation V2 API allows you to do so.

There are two types of insurance you can apply to a shipment in ShipStation V2 API:

Official parcel insurance from ShipStation
ParcelGuard: The discounted insurance rates are available to US-based accounts once you have enabled ShipStation Carriers. You can add ParcelGuard to insure shipments for any carrier.
XCover (Total Shipping Protection): The discounted insurance rates are available to UK-, ES-, DE-, IT-, and NL-based accounts once you have enabled ShipStation Carriers. You can add XCover to insure shipments for any carrier. See Total Shipping Protection by XCover.
Carrier: Carrier insurance is insurance available via the carrier selected for the shipment. Select this option if you want to add the carrier-provided insurance to the shipment. Any claim you file for the shipment would be done through your carrier's claims process.
Please note that not all carriers support adding carrier insurance. If you are unsure if your carrier supports carrier insurance, check the carrier guide or contact the carrier directly.

The official parcel insurance providers are available by account region:

Provider	`insurance_provider` value	Available to accounts based in
ParcelGuard	`parcelguard`	United States (US)
XCover (Total Shipping Protection)	`xcover`	United Kingdom (UK), Spain (ES), Germany (DE), Italy (IT), Netherlands (NL)

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 shipments with multiple packages, you'll need to set the insured_value for every package in the shipment.

Enable ParcelGuard or XCover Insurance

If you wish to use our discounted parcel insurance providers, ParcelGuard (US) or XCover (UK, ES, DE, IT, NL), you'll need to enable ShipStation Carriers in your account if you haven't already.

Log in to your ShipStation account and make sure you are in the Production environment.
Go to either the Carriers or Insurance page.
Click the Enable ShipStation Carriers button.
Confirm you have read and agreed to the terms and conditions and click the Enable services button.

Adding Insurance to a Shipment

To add insurance to a shipment, include the following properties in your request:

Shipment-Level Property

Property	Type	Description
`insurance_provider`	enumerated string	The insurance provider to use. Valid values: `none` - No insurance `shipsurance` - ShipStation insurance (legacy value) `parcelguard` - ParcelGuard insurance (US) `xcover` - XCover insurance (UK, ES, DE, IT, NL) `carrier` - Carrier-provided insurance `third_party` - Insurance arranged outside ShipStation

Package-Level Property

Property	Type	Description
`insured_value`	object	The insured value for this package. Object includes 2 properties: `currency` and `amount`.
`insured_value.currency`	string	Currency code (e.g., "usd", "gbp")
`insured_value.amount`	number	The insured value amount

Example Request

POST /v2/labels

curl -i -X POST \
  https://api.shipstation.com/v2/labels \
  -H 'Content-Type: application/json' \
  -H 'api-key: YOUR_API_KEY_HERE' \
  -d '{
    "ship_to_service_point_id": "614940",
    "ship_from_service_point_id": "614940",
    "shipment": {
      "carrier_id": "se-1234567",
      "service_code": "usps_first_class_mail",
      "requested_shipment_service": "usps_priority_mail",
      "external_order_id": "1232434",
      "hold_until_date": "2025-01-15T00:00:00.000Z",
      "ship_by_date": "2025-01-15T00:00:00.000Z",
      "deliver_by_date": "2025-01-20T00:00:00.000Z",
      "retail_rate": {
        "currency": "usd",
        "amount": 12
      },
      "store_id": "se-12345",
      "items": [],
      "notes_from_buyer": "Please handle with care",
      "notes_to_buyer": "Thank you for your order!",
      "notes_for_gift": "Happy Birthday!",
      "internal_notes": "Check packaging before shipping",
      "is_gift": true,
      "assigned_user": "user@example.com",
      "amount_paid": {
        "currency": "usd",
        "amount": 12
      },
      "shipping_paid": {
        "currency": "usd",
        "amount": 12
      },
      "tax_paid": {
        "currency": "usd",
        "amount": 12
      },
      "zone": 1,
      "display_scheme": "label",
      "tax_identifiers": [
        {
          "taxable_entity_type": "shipper",
          "identifier_type": "vat",
          "issuing_authority": "US",
          "value": "value"
        }
      ],
      "external_shipment_id": "1234556",
      "shipment_number": "10001",
      "ship_date": "2018-09-23T00:00:00Z",
      "ship_to": {
        "name": "John Doe",
        "phone": "+1 204-253-9411 ext. 123",
        "email": "example@example.com",
        "company_name": "The Home Depot",
        "address_line1": "1999 Bishop Grandin Blvd.",
        "address_line2": "Unit 408",
        "address_line3": "Building #7",
        "city_locality": "Winnipeg",
        "state_province": "Manitoba",
        "postal_code": "78756-3717",
        "country_code": "CA",
        "address_residential_indicator": "yes",
        "instructions": "any instruction",
        "geolocation": [
          {
            "type": "what3words",
            "value": "cats.with.thumbs"
          }
        ]
      },
      "ship_from": {
        "name": "John Doe",
        "phone": "+1 204-253-9411 ext. 123",
        "email": "example@example.com",
        "company_name": "The Home Depot",
        "address_line1": "1999 Bishop Grandin Blvd.",
        "address_line2": "Unit 408",
        "address_line3": "Building #7",
        "city_locality": "Winnipeg",
        "state_province": "Manitoba",
        "postal_code": "78756-3717",
        "country_code": "CA",
        "address_residential_indicator": "yes",
        "instructions": "any instructions",
        "geolocation": [
          {
            "type": "what3words",
            "value": "cats.with.thumbs"
          }
        ]
      },
      "warehouse_id": null,
      "return_to": {
        "name": "John Doe",
        "phone": "+1 204-253-9411 ext. 123",
        "email": "example@example.com",
        "company_name": "The Home Depot",
        "address_line1": "1999 Bishop Grandin Blvd.",
        "address_line2": "Unit 408",
        "address_line3": "Building #7",
        "city_locality": "Winnipeg",
        "state_province": "Manitoba",
        "postal_code": "78756-3717",
        "country_code": "CA",
        "address_residential_indicator": "yes",
        "instructions": "any instructions",
        "geolocation": [
          {
            "type": "what3words",
            "value": "cats.with.thumbs"
          }
        ]
      },
      "is_return": true,
      "confirmation": "none",
      "customs": {
        "terms_of_trade_code": "ddp",
        "contents": "gift",
        "non_delivery": "return_to_sender"
      },
      "advanced_options": {
        "bill_to_account": "123456789",
        "bill_to_country_code": "US",
        "bill_to_party": "third_party",
        "bill_to_postal_code": "28005",
        "contains_alcohol": true,
        "delivered_duty_paid": true,
        "dry_ice": true,
        "dry_ice_weight": {
          "value": 23,
          "unit": "pound"
        },
        "non_machinable": true,
        "saturday_delivery": true,
        "fedex_freight": {
          "shipper_load_and_count": "shipper_load_and_count",
          "booking_confirmation": "today"
        },
        "use_ups_ground_freight_pricing": true,
        "freight_class": "77.5",
        "custom_field1": "custom field 1",
        "custom_field2": "custom field 2",
        "custom_field3": "custom field 3",
        "origin_type": null,
        "additional_handling": true,
        "shipper_release": true,
        "collect_on_delivery": {
          "payment_type": "any",
          "payment_amount": {
            "currency": "USD",
            "amount": 12
          }
        },
        "third_party_consignee": true,
        "dangerous_goods": true,
        "dangerous_goods_contact": {
          "name": "Michael Robinson",
          "phone": "123456578789"
        },
        "movement_indicator": "b2b",
        "windsor_framework_details": {
          "movement_indicator": "b2b",
          "not_at_risk": true
        },
        "ancillary_endorsements_option": "forward",
        "return_pickup_attempts": 3,
        "own_document_upload": false,
        "limited_quantity": false,
        "event_notification": false,
        "fragile": false,
        "delivery_as_addressed": false,
        "return_after_first_attempt": false,
        "regulated_content_type": null,
        "netstamps_options": {
          "row": 1,
          "column": 1
        },
        "suppress_carrier_generated_documents": [
          "commercial_invoice"
        ],
        "transparency_codes": [
          {
            "order_item_id": "12345678901234",
            "codes": [
              "AZ:XXXXXXXXXXXX"
            ]
          }
        ]
      },
      "insurance_provider": "none",
      "tags": [],
      "order_source_code": "amazon_ca",
      "packages": [
        {
          "package_id": "se-123456",
          "package_code": "thick_envelope",
          "package_name": "Flat Rate Envelope",
          "weight": {
            "value": 23,
            "unit": "pound"
          },
          "dimensions": {
            "unit": "inch",
            "length": 2,
            "width": 2,
            "height": 1
          },
          "insured_value": {
            "currency": "usd",
            "amount": 0
          },
          "label_messages": {
            "reference1": "Reference",
            "reference2": "Reference 2",
            "reference3": "Reference 3"
          },
          "external_package_id": "se-1234545",
          "content_description": "Hand knitted wool socks",
          "products": []
        }
      ],
      "comparison_rate_type": "retail"
    },
    "is_return_label": true,
    "rma_number": "asd12323",
    "charge_event": "carrier_default",
    "outbound_label_id": "se-28529731",
    "test_label": true,
    "validate_address": "no_validation",
    "voided_at": "2018-09-23T15:00:00.000Z",
    "refund_details": {
      "amount_paid": {
        "currency": "usd",
        "amount": 12
      },
      "amount_requested": {
        "currency": "usd",
        "amount": 12
      },
      "amount_approved": {
        "currency": "usd",
        "amount": 12
      },
      "amount_credited": {
        "currency": "usd",
        "amount": 12
      }
    },
    "label_download_type": "url",
    "label_format": "pdf",
    "display_scheme": "label",
    "label_layout": "4x6",
    "label_image_id": "img_DtBXupDBxREpHnwEXhTfgK",
    "form_download": {
      "href": "https://example.com/resource",
      "type": "child"
    },
    "qr_code_download": {
      "href": "https://example.com/resource",
      "type": "child"
    },
    "paperless_download": {
      "href": "https://example.com/resource",
      "instructions": "any instructions",
      "handoff_code": "122334"
    },
    "insurance_claim": {
      "href": "https://example.com/resource",
      "type": "child"
    }
  }'

Total Shipping Protection by XCover

Total Shipping Protection by XCover is a shipment insurance option available to all ShipStation accounts based in the following countries:

🇬🇧 United Kingdom (UK)
🇪🇸 Spain (ES)
🇩🇪 Germany (DE)
🇮🇹 Italy (IT)
🇳🇱 Netherlands (NL)

To enable Total Shipping Protection, all you need to do is enable ShipStation Carriers. Once you have done so, you can start adding coverage to your shipments immediately.

Enable ShipStation Carriers in the Dashboard

You must enable ShipStation Carriers via the ShipStation dashboard. You cannot make an API call to programmatically enable ShipStation Carriers.

Once you enable ShipStation Carriers, you can add XCover as the insurance provider for any shipment, whether it ships with a ShipStation Carrier or any carrier you have connected to ShipStation.

Adding XCover Coverage

Set the shipment's insurance_provider to xcover when you get rates, create a shipment, or purchase a label.

The cost of coverage is based on the amount you assign to the amount property of the insured_value object for each package:

{
  "insured_value": {
    "currency": "eur",
    "amount": 200
  }
}

Use gbp for UK accounts and eur for ES, DE, IT, and NL accounts.

The fee for the insurance will be deducted from your ShipStation balance. See Add Funds to your ShipStation Balance for details on how to fund your balance.

Coverage Details

Total Shipping Protection covers shipments that have been lost, stolen, or damaged in transit. It will also reimburse you for return shipping costs (when your customer ships back damaged goods) and for the cost to reship new goods to your customer.

Total Shipping Protection covers the full value of domestic and international shipments up to £10,000 (UK accounts) or €10,000 (ES, DE, IT, and NL accounts). The insurance cost is a percentage of the declared value, in the currency of your account. For example, at 1.1%, insuring a £200 shipment costs £2.20.

Per XCover's terms and conditions, coverage rates depend on whether the shipment is domestic or cross-border, and on the country your account is based in.

Account country	Domestic	Cross-border
UK, ES, DE, NL	1.1%	1.5%
IT	1.63%	3.9%

Filing a Claim

To file a claim for a package insured with XCover, go to the link provided in the insurance_claim field of the shipment response and follow the on-screen instructions.

Refunds for Voided Labels

If you void a label for a shipment that includes XCover insurance, the insurance cost is immediately refunded to your ShipStation balance.

Notes about Total Shipping Protection

Some types of goods cannot be insured by Total Shipping Protection. See the terms for your country for a full list of goods that cannot be covered:

United Kingdom: Total Shipping Protection terms
Spain: Total Shipping Protection terms
Germany: Total Shipping Protection terms
Italy: Total Shipping Protection terms
Netherlands: Total Shipping Protection terms

Carrier-Specific Insurance Support

Not all carriers support carrier-provided insurance. Check your carrier's documentation guide to see if carrier insurance is supported. Common carriers that support carrier insurance include:

UPS
FedEx
DHL Express
Canada Post

If your carrier does not support carrier-provided insurance, you can use ParcelGuard (US) or XCover (UK, ES, DE, IT, NL) to insure your shipments.