API Docs

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.

Endpoints
POST
/insurances
GET
/insurances
GET
/insurances/:id
POST
/insurances/:id/refund

Insurance object

id
string
Unique identifier, begins with "ins_"
object
string
"Insurance"
mode
string
"test" or "production"
reference
string
The reference for this Insurance, if any
amount
string
USD value of insured goods with sub-cent precision
provider
string
The insurance provider used by EasyPost
provider_id
string
An identifying number for some insurance providers used by EasyPost
shipment_id
string
The ID of the Shipment in EasyPost, if postage was purchased via EasyPost
tracking_code
string
The tracking code of either the shipment within EasyPost, or provided by you during creation
status
string
The current status of the insurance, possible values are "new", "pending", "purchased", "failed", or "cancelled"
tracker
The associated Tracker object
to_address
The associated Address object for destination (optional)
from_address
The associated Address object for origin (optional)
fee
The associated insurance Fee object if any
messages
Array of strings
The list of errors encountered during attempted purchase of the insurance
created_at
datetime
When the Insurance was created
updated_at
datetime
When the Insurance was last updated
Insurance Object
{
  "id": "ins_e496d74110184165b0ab6c71b9ffc316",
  "object": "Insurance",
  "mode": "test",
  "reference": null,
  "status": "pending",
  "amount": "100.00000",
  "provider": "easypost",
  "provider_id": null,
  "to_address": {
    "id": "adr_ed83e5f92f6811f0a93dac1f6bc539ae",
    "object": "Address",
    "created_at": "2025-05-12T19:40:15+00:00",
    "updated_at": "2025-05-12T19:40:15+00:00",
    "name": "DR. STEVE BRULE",
    "company": null,
    "street1": "179 N HARBOR DR",
    "street2": null,
    "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_ed88ffb72f6811f0b5053cecef1b359e",
    "object": "Address",
    "created_at": "2025-05-12T19:40:15+00:00",
    "updated_at": "2025-05-12T19:40:15+00:00",
    "name": "EASYPOST",
    "company": null,
    "street1": "417 MONTGOMERY ST # 5",
    "street2": null,
    "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_9135862729734d96ad2f9ed0f0565a27",
    "object": "Tracker",
    "mode": "test",
    "tracking_code": "EZ1000000001",
    "status": "pre_transit",
    "status_detail": "status_update",
    "created_at": "2025-05-09T20:40:17Z",
    "updated_at": "2025-05-09T20:40:17Z",
    "signed_by": null,
    "weight": null,
    "est_delivery_date": "2025-05-09T20:40:17Z",
    "shipment_id": null,
    "carrier": "USPS",
    "tracking_details": [
      {
        "object": "TrackingDetail",
        "message": "Pre-Shipment Info Sent to USPS",
        "description": "",
        "status": "pre_transit",
        "status_detail": "status_update",
        "datetime": "2025-04-09T20:40:17Z",
        "source": "USPS",
        "carrier_code": "",
        "tracking_location": {
          "object": "TrackingLocation",
          "city": null,
          "state": null,
          "country": null,
          "zip": null
        },
        "est_delivery_date": null
      },
      {
        "object": "TrackingDetail",
        "message": "Shipping Label Created",
        "description": "",
        "status": "pre_transit",
        "status_detail": "status_update",
        "datetime": "2025-04-10T09:17:17Z",
        "source": "USPS",
        "carrier_code": "",
        "tracking_location": {
          "object": "TrackingLocation",
          "city": "HOUSTON",
          "state": "TX",
          "country": null,
          "zip": "77063"
        },
        "est_delivery_date": null
      }
    ],
    "carrier_detail": {
      "object": "CarrierDetail",
      "service": "First-Class Package Service",
      "container_type": null,
      "est_delivery_date_local": null,
      "est_delivery_time_local": null,
      "origin_location": "HOUSTON TX, 77001",
      "origin_tracking_location": {
        "object": "TrackingLocation",
        "city": "HOUSTON",
        "state": "TX",
        "country": null,
        "zip": "77063"
      },
      "destination_location": "CHARLESTON SC, 29401",
      "destination_tracking_location": null,
      "guaranteed_delivery_date": null,
      "alternate_identifier": null,
      "initial_delivery_attempt": null
    },
    "finalized": true,
    "is_return": false,
    "public_url": "https://track.easypost.com/djE6dHJrXzkxMzU4NjI3Mjk3MzRkOTZhZDJmOWVkMGYwNTY1YTI3",
    "fees": []
  },
  "tracking_code": "EZ1000000001",
  "fee": {
    "object": "Fee",
    "type": "InsuranceFee",
    "amount": "0.50000",
    "charged": true,
    "refunded": false
  },
  "messages": [],
  "created_at": "2025-05-12T19:40:15Z",
  "updated_at": "2025-05-12T19:40:15Z"
}

Create an Insurance

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

to_address
i.e. Address
The destination of the package to be insured (optional).
from_address
i.e. Address
The origin of the package to be insured (optional).
tracking_code
i.e. 9400110898825022579493
The tracking code associated with the non-EasyPost-purchased package you'd like to insure.
reference
i.e. external-order-493
An optional value that may be used in place of ID when doing Retrieve calls for this insurance.
amount
i.e. "$100.00"
The USD value of contents you would like to insure. Currently the maximum is $5000.
carrier
i.e. USPS
The carrier associated with the tracking_code you provided. The carrier will get auto-detected if none is provided.
POST /insurances
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  }'
Response
1{
2  "id": "ins_e496d74110184165b0ab6c71b9ffc316",
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_ed83e5f92f6811f0a93dac1f6bc539ae",
12    "object": "Address",
13    "created_at": "2025-05-12T19:40:15+00:00",
14    "updated_at": "2025-05-12T19:40:15+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_ed88ffb72f6811f0b5053cecef1b359e",
49    "object": "Address",
50    "created_at": "2025-05-12T19:40:15+00:00",
51    "updated_at": "2025-05-12T19:40:15+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_9135862729734d96ad2f9ed0f0565a27",
87    "object": "Tracker",
88    "mode": "test",
89    "tracking_code": "EZ1000000001",
90    "status": "pre_transit",
91    "status_detail": "status_update",
92    "created_at": "2025-05-09T20:40:17Z",
93    "updated_at": "2025-05-09T20:40:17Z",
94    "signed_by": null,
95    "weight": null,
96    "est_delivery_date": "2025-05-09T20:40:17Z",
97    "shipment_id": null,
98    "carrier": "USPS",
99    "tracking_details": [
100      {
101        "object": "TrackingDetail",
102        "message": "Pre-Shipment Info Sent to USPS",
103        "description": "",
104        "status": "pre_transit",
105        "status_detail": "status_update",
106        "datetime": "2025-04-09T20:40:17Z",
107        "source": "USPS",
108        "carrier_code": "",
109        "tracking_location": {
110          "object": "TrackingLocation",
111          "city": null,
112          "state": null,
113          "country": null,
114          "zip": null
115        },
116        "est_delivery_date": null
117      },
118      {
119        "object": "TrackingDetail",
120        "message": "Shipping Label Created",
121        "description": "",
122        "status": "pre_transit",
123        "status_detail": "status_update",
124        "datetime": "2025-04-10T09:17:17Z",
125        "source": "USPS",
126        "carrier_code": "",
127        "tracking_location": {
128          "object": "TrackingLocation",
129          "city": "HOUSTON",
130          "state": "TX",
131          "country": null,
132          "zip": "77063"
133        },
134        "est_delivery_date": null
135      }
136    ],
137    "carrier_detail": {
138      "object": "CarrierDetail",
139      "service": "First-Class Package Service",
140      "container_type": null,
141      "est_delivery_date_local": null,
142      "est_delivery_time_local": null,
143      "origin_location": "HOUSTON TX, 77001",
144      "origin_tracking_location": {
145        "object": "TrackingLocation",
146        "city": "HOUSTON",
147        "state": "TX",
148        "country": null,
149        "zip": "77063"
150      },
151      "destination_location": "CHARLESTON SC, 29401",
152      "destination_tracking_location": null,
153      "guaranteed_delivery_date": null,
154      "alternate_identifier": null,
155      "initial_delivery_attempt": null
156    },
157    "finalized": true,
158    "is_return": false,
159    "public_url": "https://track.easypost.com/djE6dHJrXzkxMzU4NjI3Mjk3MzRkOTZhZDJmOWVkMGYwNTY1YTI3",
160    "fees": []
161  },
162  "tracking_code": "EZ1000000001",
163  "fee": {
164    "object": "Fee",
165    "type": "InsuranceFee",
166    "amount": "0.50000",
167    "charged": true,
168    "refunded": false
169  },
170  "messages": [],
171  "created_at": "2025-05-12T19:40:15Z",
172  "updated_at": "2025-05-12T19:40:15Z"
173}

Retrieve all Insurances

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

before_id
i.e. ins_...
Optional pagination parameter. Only records created before the given ID will be included. May not be used with after_id.
after_id
i.e. ins_...
Optional pagination parameter. Only records created after the given ID will be included. May not be used with before_id.
start_datetime
i.e. 2016-01-02T00:00:00Z
Only return records created after this timestamp. Defaults to 1 month ago, or 1 month before a passed end_datetime.
end_datetime
i.e. 2016-01-02T00:00:00Z
Only return records created before this timestamp. Defaults to end of the current day, or 1 month after a passed start_datetime.
page_size
i.e. 30
The number of records to return on each page. The maximum value is 100, and default is 20.
GET /insurances
1curl -X GET "https://api.easypost.com/v2/insurances?page_size=5" \
2  -u "EASYPOST_API_KEY":
Response
1{
2  "insurances": [
3    {
4      "id": "ins_e496d74110184165b0ab6c71b9ffc316",
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_ed83e5f92f6811f0a93dac1f6bc539ae",
14        "object": "Address",
15        "created_at": "2025-05-12T19:40:15+00:00",
16        "updated_at": "2025-05-12T19:40:15+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_ed88ffb72f6811f0b5053cecef1b359e",
51        "object": "Address",
52        "created_at": "2025-05-12T19:40:15+00:00",
53        "updated_at": "2025-05-12T19:40:15+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_703060e9ea64437cb6233e803348b858",
89        "object": "Tracker",
90        "mode": "test",
91        "tracking_code": "EZ1000000001",
92        "status": "pre_transit",
93        "status_detail": "status_update",
94        "created_at": "2025-05-12T19:40:15Z",
95        "updated_at": "2025-05-12T19:40:16Z",
96        "signed_by": null,
97        "weight": null,
98        "est_delivery_date": "2025-05-12T19:40:15Z",
99        "shipment_id": null,
100        "carrier": "USPS",
101        "tracking_details": [
102          {
103            "object": "TrackingDetail",
104            "message": "Pre-Shipment Info Sent to USPS",
105            "description": "",
106            "status": "pre_transit",
107            "status_detail": "status_update",
108            "datetime": "2025-04-12T19:40:15Z",
109            "source": "USPS",
110            "carrier_code": "",
111            "tracking_location": {
112              "object": "TrackingLocation",
113              "city": null,
114              "state": null,
115              "country": null,
116              "zip": null
117            },
118            "est_delivery_date": null
119          },
120          {
121            "object": "TrackingDetail",
122            "message": "Shipping Label Created",
123            "description": "",
124            "status": "pre_transit",
125            "status_detail": "status_update",
126            "datetime": "2025-04-13T08:17:15Z",
127            "source": "USPS",
128            "carrier_code": "",
129            "tracking_location": {
130              "object": "TrackingLocation",
131              "city": "HOUSTON",
132              "state": "TX",
133              "country": null,
134              "zip": "77063"
135            },
136            "est_delivery_date": null
137          }
138        ],
139        "carrier_detail": {
140          "object": "CarrierDetail",
141          "service": "First-Class Package Service",
142          "container_type": null,
143          "est_delivery_date_local": null,
144          "est_delivery_time_local": null,
145          "origin_location": "HOUSTON TX, 77001",
146          "origin_tracking_location": {
147            "object": "TrackingLocation",
148            "city": "HOUSTON",
149            "state": "TX",
150            "country": null,
151            "zip": "77063"
152          },
153          "destination_location": "CHARLESTON SC, 29401",
154          "destination_tracking_location": null,
155          "guaranteed_delivery_date": null,
156          "alternate_identifier": null,
157          "initial_delivery_attempt": null
158        },
159        "finalized": true,
160        "is_return": false,
161        "public_url": "https://track.easypost.com/djE6dHJrXzcwMzA2MGU5ZWE2NDQzN2NiNjIzM2U4MDMzNDhiODU4",
162        "fees": []
163      },
164      "tracking_code": "EZ1000000001",
165      "fee": {
166        "object": "Fee",
167        "type": "InsuranceFee",
168        "amount": "0.50000",
169        "charged": true,
170        "refunded": false
171      },
172      "messages": [],
173      "created_at": "2025-05-12T19:40:15Z",
174      "updated_at": "2025-05-12T19:40:15Z"
175    }
176  ],
177  "has_more": true
178}

Retrieve an Insurance

Retrieve an Insurance by its id.

GET /insurances/:id
1curl -X GET https://api.easypost.com/v2/insurances/ins_... \
2  -u "EASYPOST_API_KEY":
Response
1{
2  "id": "ins_e496d74110184165b0ab6c71b9ffc316",
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_ed83e5f92f6811f0a93dac1f6bc539ae",
12    "object": "Address",
13    "created_at": "2025-05-12T19:40:15+00:00",
14    "updated_at": "2025-05-12T19:40:15+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_ed88ffb72f6811f0b5053cecef1b359e",
49    "object": "Address",
50    "created_at": "2025-05-12T19:40:15+00:00",
51    "updated_at": "2025-05-12T19:40:15+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_703060e9ea64437cb6233e803348b858",
87    "object": "Tracker",
88    "mode": "test",
89    "tracking_code": "EZ1000000001",
90    "status": "pre_transit",
91    "status_detail": "status_update",
92    "created_at": "2025-05-12T19:40:15Z",
93    "updated_at": "2025-05-12T19:40:16Z",
94    "signed_by": null,
95    "weight": null,
96    "est_delivery_date": "2025-05-12T19:40:15Z",
97    "shipment_id": null,
98    "carrier": "USPS",
99    "tracking_details": [
100      {
101        "object": "TrackingDetail",
102        "message": "Pre-Shipment Info Sent to USPS",
103        "description": "",
104        "status": "pre_transit",
105        "status_detail": "status_update",
106        "datetime": "2025-04-12T19:40:15Z",
107        "source": "USPS",
108        "carrier_code": "",
109        "tracking_location": {
110          "object": "TrackingLocation",
111          "city": null,
112          "state": null,
113          "country": null,
114          "zip": null
115        },
116        "est_delivery_date": null
117      },
118      {
119        "object": "TrackingDetail",
120        "message": "Shipping Label Created",
121        "description": "",
122        "status": "pre_transit",
123        "status_detail": "status_update",
124        "datetime": "2025-04-13T08:17:15Z",
125        "source": "USPS",
126        "carrier_code": "",
127        "tracking_location": {
128          "object": "TrackingLocation",
129          "city": "HOUSTON",
130          "state": "TX",
131          "country": null,
132          "zip": "77063"
133        },
134        "est_delivery_date": null
135      }
136    ],
137    "carrier_detail": {
138      "object": "CarrierDetail",
139      "service": "First-Class Package Service",
140      "container_type": null,
141      "est_delivery_date_local": null,
142      "est_delivery_time_local": null,
143      "origin_location": "HOUSTON TX, 77001",
144      "origin_tracking_location": {
145        "object": "TrackingLocation",
146        "city": "HOUSTON",
147        "state": "TX",
148        "country": null,
149        "zip": "77063"
150      },
151      "destination_location": "CHARLESTON SC, 29401",
152      "destination_tracking_location": null,
153      "guaranteed_delivery_date": null,
154      "alternate_identifier": null,
155      "initial_delivery_attempt": null
156    },
157    "finalized": true,
158    "is_return": false,
159    "public_url": "https://track.easypost.com/djE6dHJrXzcwMzA2MGU5ZWE2NDQzN2NiNjIzM2U4MDMzNDhiODU4",
160    "fees": []
161  },
162  "tracking_code": "EZ1000000001",
163  "fee": {
164    "object": "Fee",
165    "type": "InsuranceFee",
166    "amount": "0.50000",
167    "charged": true,
168    "refunded": false
169  },
170  "messages": [],
171  "created_at": "2025-05-12T19:40:15Z",
172  "updated_at": "2025-05-12T19:40:15Z"
173}

Refund an Insurance

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.

POST /insurances/:id/refund
1curl -X POST https://api.easypost.com/v2/insurances/ins_.../refund \
2  -u "EASYPOST_API_KEY":
Response
1{
2  "id": "ins_4922b4f2371d4cdb8408dc9888c70af2",
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_ee9ec2022f6811f0aa3fac1f6bc539ae",
12    "object": "Address",
13    "created_at": "2025-05-12T19:40:17+00:00",
14    "updated_at": "2025-05-12T19:40:17+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_eea32d952f6811f0aa44ac1f6bc539ae",
49    "object": "Address",
50    "created_at": "2025-05-12T19:40:17+00:00",
51    "updated_at": "2025-05-12T19:40:17+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_5e3b475600f04477ab40d44c1768c1fc",
87    "object": "Tracker",
88    "mode": "test",
89    "tracking_code": "EZ1000000001",
90    "status": "pre_transit",
91    "status_detail": "status_update",
92    "created_at": "2025-05-12T19:40:17Z",
93    "updated_at": "2025-05-12T19:40:17Z",
94    "signed_by": null,
95    "weight": null,
96    "est_delivery_date": "2025-05-12T19:40:17Z",
97    "shipment_id": null,
98    "carrier": "USPS",
99    "tracking_details": [
100      {
101        "object": "TrackingDetail",
102        "message": "Pre-Shipment Info Sent to USPS",
103        "description": "",
104        "status": "pre_transit",
105        "status_detail": "status_update",
106        "datetime": "2025-04-12T19:40:17Z",
107        "source": "USPS",
108        "carrier_code": "",
109        "tracking_location": {
110          "object": "TrackingLocation",
111          "city": null,
112          "state": null,
113          "country": null,
114          "zip": null
115        },
116        "est_delivery_date": null
117      },
118      {
119        "object": "TrackingDetail",
120        "message": "Shipping Label Created",
121        "description": "",
122        "status": "pre_transit",
123        "status_detail": "status_update",
124        "datetime": "2025-04-13T08:17:17Z",
125        "source": "USPS",
126        "carrier_code": "",
127        "tracking_location": {
128          "object": "TrackingLocation",
129          "city": "HOUSTON",
130          "state": "TX",
131          "country": null,
132          "zip": "77063"
133        },
134        "est_delivery_date": null
135      }
136    ],
137    "carrier_detail": {
138      "object": "CarrierDetail",
139      "service": "First-Class Package Service",
140      "container_type": null,
141      "est_delivery_date_local": null,
142      "est_delivery_time_local": null,
143      "origin_location": "HOUSTON TX, 77001",
144      "origin_tracking_location": {
145        "object": "TrackingLocation",
146        "city": "HOUSTON",
147        "state": "TX",
148        "country": null,
149        "zip": "77063"
150      },
151      "destination_location": "CHARLESTON SC, 29401",
152      "destination_tracking_location": null,
153      "guaranteed_delivery_date": null,
154      "alternate_identifier": null,
155      "initial_delivery_attempt": null
156    },
157    "finalized": true,
158    "is_return": false,
159    "public_url": "https://track.easypost.com/djE6dHJrXzVlM2I0NzU2MDBmMDQ0NzdhYjQwZDQ0YzE3NjhjMWZj",
160    "fees": []
161  },
162  "tracking_code": "EZ1000000001",
163  "fee": {
164    "object": "Fee",
165    "type": "InsuranceFee",
166    "amount": "0.50000",
167    "charged": true,
168    "refunded": false
169  },
170  "messages": ["Insurance was cancelled by the user."],
171  "created_at": "2025-05-12T19:40:17Z",
172  "updated_at": "2025-05-12T19:40:18Z"
173}