Insurance
An Insurance
object represents insurance for packages purchased both via the EasyPost API as well as shipments purchased through third parties and later registered with EasyPost.
An Insurance
object is created automatically whenever you buy a Shipment
through EasyPost and pass insurance options during the call,or in a later call to insure a Shipment
.
Insurance
purchased through the Shipment
buy or Shipment
insure endpoints is immediately insured -
there is no possibility of rejection based on tracking information, as the package was just created.
On the other hand, Insurance
purchased on shipments purchased outside of EasyPost requires creation with a tracking code so that EasyPost may confirm the package existence and current shipping status at the time of purchase.
Standalone insurance is created in a pending state to help distinguish it from insurance purchased for an EasyPost Shipment
.
Both kinds of Insurance
use the Tracking system to receive periodic updates, and will report those updates to any appropriate Webhook
on file.
Standalone insurance will cancel itself if the tracking information for the given tracking code shows evidence of having been shipped anytime before the insurance was purchased.
Unlike a Shipment
within EasyPost, Insurance
objects register both a to_address
and from_address
according to the destination and ship-from locations of the package.
This means that a Shipment
with its is_return
property set to true
actually ships to the listed from_address
.
Insurance
does not have a concept of is_return
, so all insurance records refer to their true package destination as to_address
, regardless of whether or not the shipment is a return.
Insurance
, if anyShipment
in EasyPost, if postage was purchased via EasyPostTracker
objectAddress
object for destination (optional)Address
object for origin (optional)Fee
object if anyInsurance
was createdInsurance
was last updated{
"id": "ins_2500e29183a64136b84a1e44ff08905f",
"object": "Insurance",
"mode": "test",
"reference": null,
"status": "pending",
"amount": "100.00000",
"provider": "easypost",
"provider_id": null,
"to_address": {
"id": "adr_568c1ebcba4c11ee96cd3cecef1b359e",
"object": "Address",
"created_at": "2024-01-24T00:05:52+00:00",
"updated_at": "2024-01-24T00:05:52+00:00",
"name": "DR. STEVE BRULE",
"company": null,
"street1": "179 N HARBOR DR",
"street2": "",
"city": "REDONDO BEACH",
"state": "CA",
"zip": "90277-2506",
"country": "US",
"phone": "8573875756",
"email": "DR_STEVE_BRULE@GMAIL.COM",
"mode": "test",
"carrier_facility": null,
"residential": false,
"federal_tax_id": null,
"state_tax_id": null,
"verifications": {
"zip4": {
"success": true,
"errors": [],
"details": null
},
"delivery": {
"success": true,
"errors": [],
"details": {
"latitude": 33.8436,
"longitude": -118.39177,
"time_zone": "America/Los_Angeles"
}
}
}
},
"from_address": {
"id": "adr_56912a8aba4c11ee96cf3cecef1b359e",
"object": "Address",
"created_at": "2024-01-24T00:05:52+00:00",
"updated_at": "2024-01-24T00:05:52+00:00",
"name": "EASYPOST",
"company": null,
"street1": "417 MONTGOMERY ST # 5",
"street2": "",
"city": "SAN FRANCISCO",
"state": "CA",
"zip": "94104-1129",
"country": "US",
"phone": "4153334445",
"email": "SUPPORT@EASYPOST.COM",
"mode": "test",
"carrier_facility": null,
"residential": false,
"federal_tax_id": null,
"state_tax_id": null,
"verifications": {
"zip4": {
"success": true,
"errors": [],
"details": null
},
"delivery": {
"success": true,
"errors": [],
"details": {
"latitude": 37.79342,
"longitude": -122.40288,
"time_zone": "America/Los_Angeles"
}
}
}
},
"shipment_id": null,
"tracker": {
"id": "trk_0ecad8116b424f00b9acdb15f66867bf",
"object": "Tracker",
"mode": "test",
"tracking_code": "9400110898825022579493",
"status": "error",
"status_detail": null,
"created_at": "2024-01-23T23:57:03Z",
"updated_at": "2024-01-23T23:57:03Z",
"signed_by": null,
"weight": null,
"est_delivery_date": null,
"shipment_id": null,
"carrier": "USPS",
"tracking_details": [
{
"object": "TrackingDetail",
"message": "In test mode, only test tracking numbers are valid. Test tracking numbers are EZ1000000001, EZ2000000002, ... , EZ7000000007",
"description": "",
"status": "error",
"status_detail": null,
"datetime": "2024-01-23T23:57:03Z",
"source": "ProcessingError",
"carrier_code": "",
"tracking_location": {
"object": "TrackingLocation",
"city": null,
"state": null,
"country": null,
"zip": null
}
}
],
"carrier_detail": null,
"finalized": true,
"is_return": false,
"public_url": "https://track.easypost.com/djE6dHJrXzBlY2FkODExNmI0MjRmMDBiOWFjZGIxNWY2Njg2N2Jm",
"fees": []
},
"tracking_code": "9400110898825022579493",
"fee": {
"object": "Fee",
"type": "InsuranceFee",
"amount": "0.50000",
"charged": true,
"refunded": false
},
"messages": [],
"created_at": "2024-01-24T00:05:52Z",
"updated_at": "2024-01-24T00:05:52Z"
}
An Insurance
created via this endpoint must belong to a shipment purchased outside of EasyPost. Insurance for a Shipment
created within EasyPost must be created via the Shipment
buy or Shipment
insure endpoints.
When creating Insurance for a non-EasyPost shipment, you must provide tracking_code, carrier, and amount information.
Customers must have their own FedEx account to insure FedEx packages.
An Insurance object is immutable once created. All information must be provided during creation; it cannot be modified later.
Request Parameters
Address
Address
1curl -X POST https://api.easypost.com/v2/insurances \
2 -u "EASYPOST_API_KEY": \
3 -H 'Content-Type: application/json' \
4 -d '{
5 "insurance": {
6 "to_address": {
7 "id": "adr_..."
8 },
9 "from_address": {
10 "id": "adr_..."
11 },
12 "tracking_code": "9400110898825022579493",
13 "carrier": "USPS",
14 "reference": "insuranceRef1",
15 "amount": "100.00"
16 }
17 }'
1{
2 "id": "ins_2500e29183a64136b84a1e44ff08905f",
3 "object": "Insurance",
4 "mode": "test",
5 "reference": null,
6 "status": "pending",
7 "amount": "100.00000",
8 "provider": "easypost",
9 "provider_id": null,
10 "to_address": {
11 "id": "adr_568c1ebcba4c11ee96cd3cecef1b359e",
12 "object": "Address",
13 "created_at": "2024-01-24T00:05:52+00:00",
14 "updated_at": "2024-01-24T00:05:52+00:00",
15 "name": "DR. STEVE BRULE",
16 "company": null,
17 "street1": "179 N HARBOR DR",
18 "street2": "",
19 "city": "REDONDO BEACH",
20 "state": "CA",
21 "zip": "90277-2506",
22 "country": "US",
23 "phone": "8573875756",
24 "email": "DR_STEVE_BRULE@GMAIL.COM",
25 "mode": "test",
26 "carrier_facility": null,
27 "residential": false,
28 "federal_tax_id": null,
29 "state_tax_id": null,
30 "verifications": {
31 "zip4": {
32 "success": true,
33 "errors": [],
34 "details": null
35 },
36 "delivery": {
37 "success": true,
38 "errors": [],
39 "details": {
40 "latitude": 33.8436,
41 "longitude": -118.39177,
42 "time_zone": "America/Los_Angeles"
43 }
44 }
45 }
46 },
47 "from_address": {
48 "id": "adr_56912a8aba4c11ee96cf3cecef1b359e",
49 "object": "Address",
50 "created_at": "2024-01-24T00:05:52+00:00",
51 "updated_at": "2024-01-24T00:05:52+00:00",
52 "name": "EASYPOST",
53 "company": null,
54 "street1": "417 MONTGOMERY ST # 5",
55 "street2": "",
56 "city": "SAN FRANCISCO",
57 "state": "CA",
58 "zip": "94104-1129",
59 "country": "US",
60 "phone": "4153334445",
61 "email": "SUPPORT@EASYPOST.COM",
62 "mode": "test",
63 "carrier_facility": null,
64 "residential": false,
65 "federal_tax_id": null,
66 "state_tax_id": null,
67 "verifications": {
68 "zip4": {
69 "success": true,
70 "errors": [],
71 "details": null
72 },
73 "delivery": {
74 "success": true,
75 "errors": [],
76 "details": {
77 "latitude": 37.79342,
78 "longitude": -122.40288,
79 "time_zone": "America/Los_Angeles"
80 }
81 }
82 }
83 },
84 "shipment_id": null,
85 "tracker": {
86 "id": "trk_0ecad8116b424f00b9acdb15f66867bf",
87 "object": "Tracker",
88 "mode": "test",
89 "tracking_code": "9400110898825022579493",
90 "status": "error",
91 "status_detail": null,
92 "created_at": "2024-01-23T23:57:03Z",
93 "updated_at": "2024-01-23T23:57:03Z",
94 "signed_by": null,
95 "weight": null,
96 "est_delivery_date": null,
97 "shipment_id": null,
98 "carrier": "USPS",
99 "tracking_details": [
100 {
101 "object": "TrackingDetail",
102 "message": "In test mode, only test tracking numbers are valid. Test tracking numbers are EZ1000000001, EZ2000000002, ... , EZ7000000007",
103 "description": "",
104 "status": "error",
105 "status_detail": null,
106 "datetime": "2024-01-23T23:57:03Z",
107 "source": "ProcessingError",
108 "carrier_code": "",
109 "tracking_location": {
110 "object": "TrackingLocation",
111 "city": null,
112 "state": null,
113 "country": null,
114 "zip": null
115 }
116 }
117 ],
118 "carrier_detail": null,
119 "finalized": true,
120 "is_return": false,
121 "public_url": "https://track.easypost.com/djE6dHJrXzBlY2FkODExNmI0MjRmMDBiOWFjZGIxNWY2Njg2N2Jm",
122 "fees": []
123 },
124 "tracking_code": "9400110898825022579493",
125 "fee": {
126 "object": "Fee",
127 "type": "InsuranceFee",
128 "amount": "0.50000",
129 "charged": true,
130 "refunded": false
131 },
132 "messages": [],
133 "created_at": "2024-01-24T00:05:52Z",
134 "updated_at": "2024-01-24T00:05:52Z"
135}
A list of all Insurance
objects associated with the given API Key
can also be retrieved. See the Pagination section of our docs for more details on retrieving all records when multiple pages are available.
Request Parameters
after_id
.before_id
.end_datetime
.start_datetime
.1curl -X GET "https://api.easypost.com/v2/insurances?page_size=5" \
2 -u "EASYPOST_API_KEY":
1{
2 "insurances": [
3 {
4 "id": "ins_2500e29183a64136b84a1e44ff08905f",
5 "object": "Insurance",
6 "mode": "test",
7 "reference": null,
8 "status": "pending",
9 "amount": "100.00000",
10 "provider": "easypost",
11 "provider_id": null,
12 "to_address": {
13 "id": "adr_568c1ebcba4c11ee96cd3cecef1b359e",
14 "object": "Address",
15 "created_at": "2024-01-24T00:05:52+00:00",
16 "updated_at": "2024-01-24T00:05:52+00:00",
17 "name": "DR. STEVE BRULE",
18 "company": null,
19 "street1": "179 N HARBOR DR",
20 "street2": null,
21 "city": "REDONDO BEACH",
22 "state": "CA",
23 "zip": "90277-2506",
24 "country": "US",
25 "phone": "8573875756",
26 "email": "DR_STEVE_BRULE@GMAIL.COM",
27 "mode": "test",
28 "carrier_facility": null,
29 "residential": false,
30 "federal_tax_id": null,
31 "state_tax_id": null,
32 "verifications": {
33 "zip4": {
34 "success": true,
35 "errors": [],
36 "details": null
37 },
38 "delivery": {
39 "success": true,
40 "errors": [],
41 "details": {
42 "latitude": 33.8436,
43 "longitude": -118.39177,
44 "time_zone": "America/Los_Angeles"
45 }
46 }
47 }
48 },
49 "from_address": {
50 "id": "adr_56912a8aba4c11ee96cf3cecef1b359e",
51 "object": "Address",
52 "created_at": "2024-01-24T00:05:52+00:00",
53 "updated_at": "2024-01-24T00:05:52+00:00",
54 "name": "EASYPOST",
55 "company": null,
56 "street1": "417 MONTGOMERY ST # 5",
57 "street2": null,
58 "city": "SAN FRANCISCO",
59 "state": "CA",
60 "zip": "94104-1129",
61 "country": "US",
62 "phone": "4153334445",
63 "email": "SUPPORT@EASYPOST.COM",
64 "mode": "test",
65 "carrier_facility": null,
66 "residential": false,
67 "federal_tax_id": null,
68 "state_tax_id": null,
69 "verifications": {
70 "zip4": {
71 "success": true,
72 "errors": [],
73 "details": null
74 },
75 "delivery": {
76 "success": true,
77 "errors": [],
78 "details": {
79 "latitude": 37.79342,
80 "longitude": -122.40288,
81 "time_zone": "America/Los_Angeles"
82 }
83 }
84 }
85 },
86 "shipment_id": null,
87 "tracker": {
88 "id": "trk_48fb9b6e8270488397cabd1ee6feccd6",
89 "object": "Tracker",
90 "mode": "test",
91 "tracking_code": "9400110898825022579493",
92 "status": "error",
93 "status_detail": null,
94 "created_at": "2024-01-24T00:05:52Z",
95 "updated_at": "2024-01-24T00:05:52Z",
96 "signed_by": null,
97 "weight": null,
98 "est_delivery_date": null,
99 "shipment_id": null,
100 "carrier": "USPS",
101 "tracking_details": [
102 {
103 "object": "TrackingDetail",
104 "message": "In test mode, only test tracking numbers are valid. Test tracking numbers are EZ1000000001, EZ2000000002, ... , EZ7000000007",
105 "description": "",
106 "status": "error",
107 "status_detail": null,
108 "datetime": "2024-01-24T00:05:52Z",
109 "source": "ProcessingError",
110 "carrier_code": "",
111 "tracking_location": {
112 "object": "TrackingLocation",
113 "city": null,
114 "state": null,
115 "country": null,
116 "zip": null
117 }
118 }
119 ],
120 "carrier_detail": null,
121 "finalized": true,
122 "is_return": false,
123 "public_url": "https://track.easypost.com/djE6dHJrXzQ4ZmI5YjZlODI3MDQ4ODM5N2NhYmQxZWU2ZmVjY2Q2",
124 "fees": []
125 },
126 "tracking_code": "9400110898825022579493",
127 "fee": {
128 "object": "Fee",
129 "type": "InsuranceFee",
130 "amount": "0.50000",
131 "charged": true,
132 "refunded": false
133 },
134 "messages": [],
135 "created_at": "2024-01-24T00:05:52Z",
136 "updated_at": "2024-01-24T00:05:52Z"
137 }
138 ],
139 "has_more": true
140}
Retrieve an Insurance
by its id
.
1curl -X GET https://api.easypost.com/v2/insurances/ins_... \
2 -u "EASYPOST_API_KEY":
1{
2 "id": "ins_2500e29183a64136b84a1e44ff08905f",
3 "object": "Insurance",
4 "mode": "test",
5 "reference": null,
6 "status": "pending",
7 "amount": "100.00000",
8 "provider": "easypost",
9 "provider_id": null,
10 "to_address": {
11 "id": "adr_568c1ebcba4c11ee96cd3cecef1b359e",
12 "object": "Address",
13 "created_at": "2024-01-24T00:05:52+00:00",
14 "updated_at": "2024-01-24T00:05:52+00:00",
15 "name": "DR. STEVE BRULE",
16 "company": null,
17 "street1": "179 N HARBOR DR",
18 "street2": null,
19 "city": "REDONDO BEACH",
20 "state": "CA",
21 "zip": "90277-2506",
22 "country": "US",
23 "phone": "8573875756",
24 "email": "DR_STEVE_BRULE@GMAIL.COM",
25 "mode": "test",
26 "carrier_facility": null,
27 "residential": false,
28 "federal_tax_id": null,
29 "state_tax_id": null,
30 "verifications": {
31 "zip4": {
32 "success": true,
33 "errors": [],
34 "details": null
35 },
36 "delivery": {
37 "success": true,
38 "errors": [],
39 "details": {
40 "latitude": 33.8436,
41 "longitude": -118.39177,
42 "time_zone": "America/Los_Angeles"
43 }
44 }
45 }
46 },
47 "from_address": {
48 "id": "adr_56912a8aba4c11ee96cf3cecef1b359e",
49 "object": "Address",
50 "created_at": "2024-01-24T00:05:52+00:00",
51 "updated_at": "2024-01-24T00:05:52+00:00",
52 "name": "EASYPOST",
53 "company": null,
54 "street1": "417 MONTGOMERY ST # 5",
55 "street2": null,
56 "city": "SAN FRANCISCO",
57 "state": "CA",
58 "zip": "94104-1129",
59 "country": "US",
60 "phone": "4153334445",
61 "email": "SUPPORT@EASYPOST.COM",
62 "mode": "test",
63 "carrier_facility": null,
64 "residential": false,
65 "federal_tax_id": null,
66 "state_tax_id": null,
67 "verifications": {
68 "zip4": {
69 "success": true,
70 "errors": [],
71 "details": null
72 },
73 "delivery": {
74 "success": true,
75 "errors": [],
76 "details": {
77 "latitude": 37.79342,
78 "longitude": -122.40288,
79 "time_zone": "America/Los_Angeles"
80 }
81 }
82 }
83 },
84 "shipment_id": null,
85 "tracker": {
86 "id": "trk_48fb9b6e8270488397cabd1ee6feccd6",
87 "object": "Tracker",
88 "mode": "test",
89 "tracking_code": "9400110898825022579493",
90 "status": "error",
91 "status_detail": null,
92 "created_at": "2024-01-24T00:05:52Z",
93 "updated_at": "2024-01-24T00:05:52Z",
94 "signed_by": null,
95 "weight": null,
96 "est_delivery_date": null,
97 "shipment_id": null,
98 "carrier": "USPS",
99 "tracking_details": [
100 {
101 "object": "TrackingDetail",
102 "message": "In test mode, only test tracking numbers are valid. Test tracking numbers are EZ1000000001, EZ2000000002, ... , EZ7000000007",
103 "description": "",
104 "status": "error",
105 "status_detail": null,
106 "datetime": "2024-01-24T00:05:52Z",
107 "source": "ProcessingError",
108 "carrier_code": "",
109 "tracking_location": {
110 "object": "TrackingLocation",
111 "city": null,
112 "state": null,
113 "country": null,
114 "zip": null
115 }
116 }
117 ],
118 "carrier_detail": null,
119 "finalized": true,
120 "is_return": false,
121 "public_url": "https://track.easypost.com/djE6dHJrXzQ4ZmI5YjZlODI3MDQ4ODM5N2NhYmQxZWU2ZmVjY2Q2",
122 "fees": []
123 },
124 "tracking_code": "9400110898825022579493",
125 "fee": {
126 "object": "Fee",
127 "type": "InsuranceFee",
128 "amount": "0.50000",
129 "charged": true,
130 "refunded": false
131 },
132 "messages": [],
133 "created_at": "2024-01-24T00:05:52Z",
134 "updated_at": "2024-01-24T00:05:52Z"
135}
Refunding Insurance
is only available for standalone insurance purchased through EasyPost. The tracking status for the insurance must be either pre_transit
, cancelled
, or unknown
in order to be eligible.
1curl -X POST https://api.easypost.com/v2/insurances/ins_.../refund \
2 -u "EASYPOST_API_KEY":
1{
2 "id": "ins_2500e29183a64136b84a1e44ff08905f",
3 "object": "Insurance",
4 "mode": "test",
5 "reference": null,
6 "status": "cancelled",
7 "amount": "100.00000",
8 "provider": "easypost",
9 "provider_id": null,
10 "to_address": {
11 "id": "adr_568c1ebcba4c11ee96cd3cecef1b359e",
12 "object": "Address",
13 "created_at": "2024-01-24T00:05:52+00:00",
14 "updated_at": "2024-01-24T00:05:52+00:00",
15 "name": "DR. STEVE BRULE",
16 "company": null,
17 "street1": "179 N HARBOR DR",
18 "street2": null,
19 "city": "REDONDO BEACH",
20 "state": "CA",
21 "zip": "90277-2506",
22 "country": "US",
23 "phone": "8573875756",
24 "email": "DR_STEVE_BRULE@GMAIL.COM",
25 "mode": "test",
26 "carrier_facility": null,
27 "residential": false,
28 "federal_tax_id": null,
29 "state_tax_id": null,
30 "verifications": {
31 "zip4": {
32 "success": true,
33 "errors": [],
34 "details": null
35 },
36 "delivery": {
37 "success": true,
38 "errors": [],
39 "details": {
40 "latitude": 33.8436,
41 "longitude": -118.39177,
42 "time_zone": "America/Los_Angeles"
43 }
44 }
45 }
46 },
47 "from_address": {
48 "id": "adr_56912a8aba4c11ee96cf3cecef1b359e",
49 "object": "Address",
50 "created_at": "2024-01-24T00:05:52+00:00",
51 "updated_at": "2024-01-24T00:05:52+00:00",
52 "name": "EASYPOST",
53 "company": null,
54 "street1": "417 MONTGOMERY ST # 5",
55 "street2": null,
56 "city": "SAN FRANCISCO",
57 "state": "CA",
58 "zip": "94104-1129",
59 "country": "US",
60 "phone": "4153334445",
61 "email": "SUPPORT@EASYPOST.COM",
62 "mode": "test",
63 "carrier_facility": null,
64 "residential": false,
65 "federal_tax_id": null,
66 "state_tax_id": null,
67 "verifications": {
68 "zip4": {
69 "success": true,
70 "errors": [],
71 "details": null
72 },
73 "delivery": {
74 "success": true,
75 "errors": [],
76 "details": {
77 "latitude": 37.79342,
78 "longitude": -122.40288,
79 "time_zone": "America/Los_Angeles"
80 }
81 }
82 }
83 },
84 "shipment_id": null,
85 "tracker": {
86 "id": "trk_48fb9b6e8270488397cabd1ee6feccd6",
87 "object": "Tracker",
88 "mode": "test",
89 "tracking_code": "9400110898825022579493",
90 "status": "error",
91 "status_detail": null,
92 "created_at": "2024-01-24T00:05:52Z",
93 "updated_at": "2024-01-24T00:05:52Z",
94 "signed_by": null,
95 "weight": null,
96 "est_delivery_date": null,
97 "shipment_id": null,
98 "carrier": "USPS",
99 "tracking_details": [
100 {
101 "object": "TrackingDetail",
102 "message": "In test mode, only test tracking numbers are valid. Test tracking numbers are EZ1000000001, EZ2000000002, ... , EZ7000000007",
103 "description": "",
104 "status": "error",
105 "status_detail": null,
106 "datetime": "2024-01-24T00:05:52Z",
107 "source": "ProcessingError",
108 "carrier_code": "",
109 "tracking_location": {
110 "object": "TrackingLocation",
111 "city": null,
112 "state": null,
113 "country": null,
114 "zip": null
115 }
116 }
117 ],
118 "carrier_detail": null,
119 "finalized": true,
120 "is_return": false,
121 "public_url": "https://track.easypost.com/djE6dHJrXzQ4ZmI5YjZlODI3MDQ4ODM5N2NhYmQxZWU2ZmVjY2Q2",
122 "fees": []
123 },
124 "tracking_code": "9400110898825022579493",
125 "fee": {
126 "object": "Fee",
127 "type": "InsuranceFee",
128 "amount": "0.50000",
129 "charged": true,
130 "refunded": false
131 },
132 "messages": ["Insurance was cancelled by the user."],
133 "created_at": "2024-01-24T00:05:52Z",
134 "updated_at": "2024-01-24T00:05:52Z"
135}