Insurance

Through Shippo you can purchase discounted insurance from our partner Shipsurance or directly from carriers themselves.

About insurance

Shippo (via Shipsurance) currently offers coverage for shipments sent with USPS, UPS, FedEx, DHL Express, and Canada Post.

Alternatively you can purchase insurance directly from FedEx, UPS, and Ontrac from the Shipment extras attribute. However, we recommend using Shippo's built-in insurance - it offers a more comprehensive coverage at a lower price.

Insurance for single package shipments

For shipments consisting of only one package, you can specify insurance directly from the Shipment object.

Make sure to specify the insurance_amount and insurance_currency, as well as insurance_content within the ShipmentExtras attribute. The insurance_provider will default to Shippo's insurance provider.

curl https://api.goshippo.com/shipments/ \
    -H "Authorization: ShippoToken <API_TOKEN>" \
    -d object_purpose="PURCHASE" \
    -d address_from="d799c2679e644279b59fe661ac8fa488" \
    -d address_to="42236bcf36214f62bcc6d7f12f02a849" \
    -d parcel="7df2ecf8b4224763ab7c71fae7ec8274" \
    -d insurance_amount="200" \
    -d insurance_currency="USD" \
    -d extra='{"insurance_content": "t-shirts" }' \
    -d async=false
require 'shippo'

Shippo::api_token = '<API_TOKEN>'

address_from = {
    :object_purpose => 'PURCHASE',
    :name => 'Shawn Ippotle',
    :street1 => '215 Clayton St.',
    :city => 'San Francisco',
    :state => 'CA',
    :zip => '94117',
    :country => 'US',
    :phone => '+1 555 341 9393',
    :email => 'shippotle@goshippo.com' 
}

address_to = {
    :object_purpose => 'PURCHASE',
    :name => 'Mr Hippo',
    :street1 => 'Broadway 1',
    :city => 'New York',
    :state => 'NY',
    :zip => '10007',
    :country => 'US',
    :phone => '+1 555 341 9393',
    :email => 'mrhippo@goshippo.com'
}

parcel = {
    :length => 5,
    :width => 1,
    :height => 5.555,
    :distance_unit => :in,
    :weight => 2,
    :mass_unit => :lb
}

shipment = Shippo::Shipment.create(
    :object_purpose => 'PURCHASE',
    :address_from => address_from,
    :address_to => address_to,
    :parcel => parcel,
    :async => false,
    :insurance_amount => "200",
    :insurance_currency => "USD",
    :extra => { "insurance_content": "t-shirts" }
)
import shippo

shippo.api_key = "<API_TOKEN>"

address_from = {
    "object_purpose": "PURCHASE",
    "name": "Shawn Ippotle",
    "street1": "215 Clayton St.",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94117",
    "country": "US",
    "phone": "+1 555 341 9393",
    "email": "shippotle@goshippo.com"
}

address_to = {
    "object_purpose": "PURCHASE",
    "name": "Mr Hippo",
    "street1": "Broadway 1",
    "city": "New York",
    "state": "NY",
    "zip": "10007",
    "country": "US",
    "phone": "+1 555 341 9393",
    "email": "mrhippo@goshippo.com"
}

parcel = {
    "length": "5",
    "width": "5",
    "height": "5",
    "distance_unit": "in",
    "weight": "2",
    "mass_unit": "lb"
}

shipment = shippo.Shipment.create(
    object_purpose = 'PURCHASE',
    address_from = address_from,
    address_to = address_to,
    parcel = parcel,
    async = False,
    insurance_amount = "200",
    insurance_currency = "USD",
    extra = { "insurance_content": "t-shirts" }
)
require_once('lib/Shippo.php');
Shippo::setApiKey("<API_TOKEN>");

$fromAddress = array(
    'object_purpose' => 'PURCHASE',
    'name' => 'Shawn Ippotle',
    'street1' => '215 Clayton St.',
    'city' => 'San Francisco',
    'state' => 'CA',
    'zip' => '94117',
    'country' => 'US',
    'phone' => '+1 555 341 9393',
    'email' => 'shippotle@goshippo.com'
);

$toAddress = array(
    'object_purpose' => 'PURCHASE',
    'name' => 'Mr Hippo"',
    'street1' => 'Broadway 1',
    'city' => 'New York',
    'state' => 'NY',
    'zip' => '10007',
    'country' => 'US',
    'phone' => '+1 555 341 9393',
    'email' => 'mrhippo@goshippo.com'
);

$parcel = array(
    'length'=> '5',
    'width'=> '5',
    'height'=> '5',
    'distance_unit'=> 'in',
    'weight'=> '2',
    'mass_unit'=> 'lb',
);

$shipment = Shippo_Shipment::create(
    array(
        "object_purpose" => "PURCHASE",
        "address_from" => $fromAddress,
        "address_to" => $toAddress,
        "parcel" => $parcel,
        "async" => false,
        "insurance_amount" => "200",
        "insurance_currency" => "USD",
        "extra" => array("insurance_content" => "t-shirts")
    )
);
var shippo = require('shippo')('<API_TOKEN>');

var addressFrom  = {
    "object_purpose": "PURCHASE",
    "name": "Shawn Ippotle",
    "street1": "215 Clayton St.",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94117",
    "country": "US",
    "phone": "+1 555 341 9393",
    "email": "shippotle@goshippo.com"
};

var addressTo = {
    "object_purpose": "PURCHASE",
    "name": "Mr Hippo",
    "street1": "Broadway 1",
    "city": "New York",
    "state": "NY",
    "zip": "10007",
    "country": "US",
    "phone": "+1 555 341 9393",
    "email": "mrhippo@goshippo.com"
};

var parcel = {
    "length": "5",
    "width": "5",
    "height": "5",
    "distance_unit": "in",
    "weight": "2",
    "mass_unit": "lb"
};

shippo.shipment.create({
    "object_purpose": "PURCHASE",
    "address_from": addressFrom,
    "address_to": addressTo,
    "parcel": parcel,
    "async": true,
    "insurance_amount": "200",
    "insurance_currency": "USD",
    "extra": { "insurance_content": "t-shirts" },
}, function(err, shipment) {
   // asynchronously called
});

APIResource resource = new APIResource ('<API_TOKEN>');

// to address
Hashtable toAddressTable = new Hashtable();
toAddressTable.Add("object_purpose", "PURCHASE");
toAddressTable.Add("name", "Mr Hippo");
toAddressTable.Add("company", "Shippo");
toAddressTable.Add("street1", "215 Clayton St.");
toAddressTable.Add("city", "San Francisco");
toAddressTable.Add("state", "CA");
toAddressTable.Add("zip", "94117");
toAddressTable.Add("country", "US");
toAddressTable.Add("phone", "+1 555 341 9393");
toAddressTable.Add("email", "mrhippo@goshipppo.com");

// from address
Hashtable fromAddressTable = new Hashtable();
fromAddressTable.Add("object_purpose", "PURCHASE");
fromAddressTable.Add("name", "Ms Hippo");
fromAddressTable.Add("company", "San Diego Zoo");
fromAddressTable.Add("street1", "2920 Zoo Drive");
fromAddressTable.Add("city", "San Diego");
fromAddressTable.Add("state", "CA");
fromAddressTable.Add("zip", "92101");
fromAddressTable.Add("country", "US");
fromAddressTable.Add("email", "mshippo@goshipppo.com");
fromAddressTable.Add("phone", "+1 619 231 1515");
fromAddressTable.Add("metadata", "Customer ID 123456");

// parcel
Hashtable parcelTable = new Hashtable ();
    parcelTable.Add ("length", "5");
    parcelTable.Add ("width", "5");
    parcelTable.Add ("height", "5");
    parcelTable.Add ("distance_unit", "in");
    parcelTable.Add ("weight", "2");
    parcelTable.Add ("mass_unit", "lb");

resource.CreateShipment(new Hashtable() {
    { "address_from", fromAddressTable},
    { "object_purpose", "PURCHASE"},
    { "address_to", toAddressTable},
    { "parcel", parcelTable},
    { "insurance_amount", "200"},
    { "insurance_currency", "USD"},
    { "extra", new Hashtable() {
            { "insurance_content", "t-shirts"}
        }
    }
    { "async", false}});

Each valid Shipment object request will trigger a number of Rate objects that contain the Shipment insurance information as well.

{
    "object_state": "VALID",
    "object_status": "SUCCESS",
    "object_purpose": "PURCHASE",
    "object_created": "2013-12-01T06:24:20.121Z",
    "object_updated": "2013-12-01T06:24:20.121Z",
    "object_id": "5e40ead7cffe4cc1ad45108696162e42",
    "object_owner": "shippotle@goshippo.com",
    "address_from": "4f406a13253945a8bc8deb0f8266b245",
    "address_to": "4c7185d353764d0985a6a7825aed8ffb",
    "address_return": "4f406a13253945a8bc8deb0f8266b245",
    "parcel": "ec952343dd4843c39b42aca620471fd5",
    "submission_date": "2013-12-03T12:00:00.000Z",
    "insurance_amount": "200",
    "insurance_currency": "USD",
    "extra": { "insurance_content": "t-shirts" },
    "customs_declaration": "",
    "reference_1": "",
    "reference_2": "",
    "rates_url": "https://api.goshippo.com/shipments/5e40ead7cffe4cc1ad45108696162e42/rates/",
    "rates_list": [
        {
            "object_state": "VALID",
            "object_purpose": "PURCHASE",
            "object_created": "2013-12-01T06:24:21.121Z",
            "object_updated": "2013-12-01T06:24:21.121Z",
            "object_id": "545ab0a1a6ea4c9f9adb2512a57d6d8b",
            "object_owner": "shippotle@goshippo.com",
            "shipment": "5e40ead7cffe4cc1ad45108696162e42",
            "attributes": [],
            "amount": "5.50",
            "currency": "USD",
            "amount_local": "5.50",
            "currency_local": "USD",
            "provider": "USPS",
            "provider_image_75": "https://cdn2.goshippo.com/providers/75/USPS.png",
            "provider_image_200": "https://cdn2.goshippo.com/providers/200/USPS.png",
            "servicelevel_name": "Priority Mail",
            "servicelevel_token":"usps_priority",
            "servicelevel_terms": "",
            "days": 2,
            "arrives_by": null,
            "duration_terms": "Delivery in 1 to 3 business days.",
            "trackable": true,
            "insurance": true,
            "insurance_amount_local": "200.00",
            "insurance_currency_local": "USD",
            "insurance_amount": "200.00",
            "insurance_currency": "USD",
            "messages": [],
            "carrier_account": "078870331023437cb917f5187429b093",
            "test": false
        },
        ...
    ],
    "carrier_accounts": [],
    "metadata": "Customer ID 123456",
    "messages": []
}

You can then create the shipping label by POSTing to the Transaction endpoint as usual:

curl https://api.goshippo.com/transactions \
    -H "Authorization: ShippoToken <API_TOKEN>" \
    -d rate="cf6fea899f1848b494d9568e8266e076"
    -d label_file_type="PDF"
    -d async=false
# Get the first rate in the rates results.
# Customize this based on your business logic.
rate = shipment.rates_list.first

# Purchase the desired rate.
transaction = Shippo::Transaction.create( 
  :rate => rate["object_id"], 
  :label_file_type => "PDF", 
  :async => false )

# label_url and tracking_number
if transaction["object_status"] == "SUCCESS"
  puts "Label sucessfully generated:"
  puts "label_url: #{transaction.label_url}" 
  puts "tracking_number: #{transaction.tracking_number}" 
else
  puts "Error generating label:"
  puts transaction.messages
end
# Get the first rate in the rates results.
# Customize this based on your business logic.
rate = shipment.rates_list[0]

# Purchase the desired rate. 
transaction = shippo.Transaction.create( 
    rate=rate.object_id, 
    label_file_type="PDF", 
    async=False )

# Retrieve label url and tracking number or error message
if transaction.object_status == "SUCCESS":
    print transaction.label_url
    print transaction.tracking_number
else:
    print transaction.messages
// Get the first rate in the rates results.
// Customize this based on your business logic.
$rate = $shipment["rates_list"][0];

// Purchase the desired rate.
$transaction = Shippo_Transaction::create( array( 
    'rate' => $rate["object_id"], 
    'label_file_type' => "PDF", 
    'async' => false ) );

// Retrieve label url and tracking number or error message
if ($transaction["object_status"] == "SUCCESS"){
    echo( $transaction["label_url"] );
    echo("\n");
    echo( $transaction["tracking_number"] );
}else {
    echo( $transaction["messages"] );
}
// Get the first rate in the rates results.
// Customize this based on your business logic.
var rate = shipment.rates_list[0];

// Purchase the desired rate.
shippo.transaction.create({
    "rate": rate.object_id,
    "label_file_type": "PDF",
    "async": false
}, function(err, transaction) {
   // asynchronous callback
});
// Get the first rate in the rates results.
// Customize this based on your business logic.
Rate rate = shipment.RatesList[0];

HashMap transactionParameters = new HashMap();
transactionParameters.Add("rate", rate.ObjectId);
transactionParameters.Add("async", false);

// Purchase the desired rate.
Transaction transaction = resource.CreateTransaction(transactionParameters);

if (transaction.getObjectStatus().equals("SUCCESS")){
    Console.WriteLine("Label url: " + transaction.getLabelUrl());
    Console.WriteLine("Tracking number: " + transaction.getTrackingNumber());
} else{
    Console.WriteLine("Error generating label. Messages: " + transaction.getMessages());
}

Insurance for multi-piece shipments

For multi-piece shipments you can choose to purchase specific insurance amounts for each package. This can be done through the extras attribute when creating your Parcel object within the Shipment request.

Parcel-level coverage is only available for purchase through FedEx and UPS. Shipsurance insurance can only be applied on a Shipment-level for single package shipments.

Creating a label with one API call is like one big, nested POST request to the Transaction endpoint. The structure of the content can be summarized as follows:

curl https://api.goshippo.com/shipment/  \
-H "Authorization: ShippoToken <API_TOKEN>" \
-H "Content-Type: application/json"  \
-d '{
    "object_purpose": "PURCHASE",
    "address_from": "d799c2679e644279b59fe661ac8fa488",
    "address_to": "42236bcf36214f62bcc6d7f12f02a849",
    "parcel": [
        {
            "length": "5",
            "width": "5",
            "height": "5",
            "distance_unit": "cm",
            "weight": "2",
            "mass_unit": "lb",
            "template": "",
            "metadata": "Box1",
            "extra": {
                "insurance": {
                    "amount": 25.00,
                    "currency": "USD",
                    "provider": "FEDEX"
                    }
            }
        },
        {
            "length": "5",
            "width": "10",
            "height": "15",
            "distance_unit": "cm",
            "weight": "6",
            "mass_unit": "lb",
            "template": "",
            "metadata": "Box2",
            "extra": {
                "insurance": {
                    "amount": 50.00,
                    "currency": "USD",
                    "provider": "FEDEX"
                    }
            }
        },
        {
            "length": "2",
            "width": "8",
            "height": "9",
            "distance_unit": "cm",
            "weight": "5",
            "mass_unit": "lb",
            "template": "",
            "metadata": "Box3",
            "extra": {
                "insurance": {
                    "amount": 45.00,
                    "currency": "USD",
                    "provider": "FEDEX"
                    }
            }
        }
    ],
    "async": false
}

Handling Shipment-level and Parcel-level Insurance

If both shipment-level and parcel-level insurance are specified, the parcel-level insurance will take precedence. Parcels without parcel-level insurance will have the shipment-level insurance amount applied to that parcel.

If only shipment-level insurance is specified, then the shipment insurance amount will be applied to each parcel - not divide amongst parcels.

Calculating the cost of insurance

The insurance_amount field in the Rate object shows the amount your package is insured for. The cost of the insurance itself is factored into the Rate's amount field, which reflects the full cost of the Shipment (the cost of the label plus the insurance amount).

Shipsurance rates:

  • $0.45 per $100 of insured value of a domestic shipment
  • $0.75 per $100 of insured value of a international shipment.

For instance, if you insured a domestic shipment of $125, your insurance cost would be $0.90.

For insurance through carrier themselves, please refer to your contract.