Shipping Refund
USPS shipping labels can be refunded if requested within 30 days of generation. The processing time is at least 15 days, after which the funds will return to your EasyPost balance. EasyPost fees will also be refunded. To qualify, a shipment must not have been scanned by the USPS.
UPS and FedEx shipping labels may be refunded within 90 days of creation.
Endpoints
Refunding a Shipment is available for many carriers
supported by EasyPost.
Once the refund has been submitted, refund_status attribute of the Shipment will be populated with one of the possible values:
- "submitted"
- "refunded"
- "rejected"
- "not_applicable"
The most common initial status is "submitted".
Many carriers require that the refund be processed before the refund_status will move to "refunded".
The length of this process depends on the carrier, but no greater than 30 days.
POST /
1curl -X POST https://api.easypost.com/v2/shipments/shp_.../refund \
2 -u "EASYPOST_API_KEY":Response
1{
2 "id": "shp_597ccf75eb5f441282d22199e802474b",
3 "created_at": "2025-05-09T20:40:14Z",
4 "is_return": false,
5 "messages": [],
6 "mode": "test",
7 "options": {
8 "currency": "USD",
9 "payment": {
10 "type": "SENDER"
11 },
12 "date_advance": 0
13 },
14 "reference": null,
15 "status": "unknown",
16 "tracking_code": "9405500208303109884199",
17 "updated_at": "2025-05-09T20:40:15Z",
18 "batch_id": null,
19 "batch_status": null,
20 "batch_message": null,
21 "customs_info": {
22 "id": "cstinfo_019953a528634e2c872bbd967ce5600f",
23 "object": "CustomsInfo",
24 "created_at": "2025-05-09T20:40:14Z",
25 "updated_at": "2025-05-09T20:40:14Z",
26 "contents_explanation": "",
27 "contents_type": "merchandise",
28 "customs_certify": true,
29 "customs_signer": "Steve Brule",
30 "eel_pfc": "NOEEI 30.37(a)",
31 "non_delivery_option": "return",
32 "restriction_comments": null,
33 "restriction_type": "none",
34 "mode": "test",
35 "declaration": null,
36 "customs_items": [
37 {
38 "id": "cstitem_8312791adb0f404bb9649793108d5005",
39 "object": "CustomsItem",
40 "created_at": "2025-05-09T20:40:14Z",
41 "updated_at": "2025-05-09T20:40:14Z",
42 "description": "T-shirt",
43 "hs_tariff_number": "123456",
44 "origin_country": "US",
45 "quantity": 1,
46 "value": "10.0",
47 "weight": 5.0,
48 "code": "123",
49 "mode": "test",
50 "manufacturer": null,
51 "currency": null,
52 "eccn": null,
53 "printed_commodity_identifier": null
54 }
55 ]
56 },
57 "from_address": {
58 "id": "adr_cf698f942d1511f0ba403cecef1b359e",
59 "object": "Address",
60 "created_at": "2025-05-09T20:40:14+00:00",
61 "updated_at": "2025-05-09T20:40:14+00:00",
62 "name": "EasyPost",
63 "company": null,
64 "street1": "417 Montgomery Street",
65 "street2": "5th Floor",
66 "city": "San Francisco",
67 "state": "CA",
68 "zip": "94104",
69 "country": "US",
70 "phone": "4153334445",
71 "email": "support@easypost.com",
72 "mode": "test",
73 "carrier_facility": null,
74 "residential": null,
75 "federal_tax_id": null,
76 "state_tax_id": null,
77 "verifications": {}
78 },
79 "insurance": null,
80 "order_id": null,
81 "parcel": {
82 "id": "prcl_2f24a6b6933e4e6a8014db18d1a5c1e5",
83 "object": "Parcel",
84 "created_at": "2025-05-09T20:40:14Z",
85 "updated_at": "2025-05-09T20:40:14Z",
86 "length": 20.2,
87 "width": 10.9,
88 "height": 5.0,
89 "predefined_package": null,
90 "weight": 65.9,
91 "mode": "test"
92 },
93 "postage_label": {
94 "object": "PostageLabel",
95 "id": "pl_e418f892afdd4cc88800666cac351037",
96 "created_at": "2025-05-09T20:40:15Z",
97 "updated_at": "2025-05-09T20:40:15Z",
98 "date_advance": 0,
99 "integrated_form": "none",
100 "label_date": "2025-05-09T20:40:15Z",
101 "label_resolution": 300,
102 "label_size": "4x6",
103 "label_type": "default",
104 "label_file_type": "image/png",
105 "label_url": "https://easypost-files.s3.us-west-2.amazonaws.com/files/postage_label/20250509/e88edd47ea734745ad9bcac25981bbcc78.png",
106 "label_pdf_url": null,
107 "label_zpl_url": null,
108 "label_epl2_url": null,
109 "label_file": null
110 },
111 "rates": [
112 {
113 "id": "rate_dc729315aec94bd79b07d21e4ba4d237",
114 "object": "Rate",
115 "created_at": "2025-05-09T20:40:14Z",
116 "updated_at": "2025-05-09T20:40:14Z",
117 "mode": "test",
118 "service": "GroundAdvantage",
119 "carrier": "USPS",
120 "rate": "8.20",
121 "currency": "USD",
122 "retail_rate": "13.85",
123 "retail_currency": "USD",
124 "list_rate": "9.74",
125 "list_currency": "USD",
126 "billing_type": "easypost",
127 "delivery_days": 3,
128 "delivery_date": null,
129 "delivery_date_guaranteed": false,
130 "est_delivery_days": 3,
131 "shipment_id": "shp_597ccf75eb5f441282d22199e802474b",
132 "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
133 },
134 {
135 "id": "rate_a4859235721c4de9b606872dc4602424",
136 "object": "Rate",
137 "created_at": "2025-05-09T20:40:14Z",
138 "updated_at": "2025-05-09T20:40:14Z",
139 "mode": "test",
140 "service": "Express",
141 "carrier": "USPS",
142 "rate": "51.20",
143 "currency": "USD",
144 "retail_rate": "59.25",
145 "retail_currency": "USD",
146 "list_rate": "51.20",
147 "list_currency": "USD",
148 "billing_type": "easypost",
149 "delivery_days": 2,
150 "delivery_date": null,
151 "delivery_date_guaranteed": false,
152 "est_delivery_days": 2,
153 "shipment_id": "shp_597ccf75eb5f441282d22199e802474b",
154 "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
155 },
156 {
157 "id": "rate_607cb5d222044ad8a8ce49732d9492f1",
158 "object": "Rate",
159 "created_at": "2025-05-09T20:40:14Z",
160 "updated_at": "2025-05-09T20:40:14Z",
161 "mode": "test",
162 "service": "Priority",
163 "carrier": "USPS",
164 "rate": "11.01",
165 "currency": "USD",
166 "retail_rate": "15.40",
167 "retail_currency": "USD",
168 "list_rate": "11.01",
169 "list_currency": "USD",
170 "billing_type": "easypost",
171 "delivery_days": 2,
172 "delivery_date": null,
173 "delivery_date_guaranteed": false,
174 "est_delivery_days": 2,
175 "shipment_id": "shp_597ccf75eb5f441282d22199e802474b",
176 "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
177 }
178 ],
179 "refund_status": "submitted",
180 "scan_form": null,
181 "selected_rate": {
182 "id": "rate_607cb5d222044ad8a8ce49732d9492f1",
183 "object": "Rate",
184 "created_at": "2025-05-09T20:40:15Z",
185 "updated_at": "2025-05-09T20:40:15Z",
186 "mode": "test",
187 "service": "Priority",
188 "carrier": "USPS",
189 "rate": "11.01",
190 "currency": "USD",
191 "retail_rate": "15.40",
192 "retail_currency": "USD",
193 "list_rate": "11.01",
194 "list_currency": "USD",
195 "billing_type": "easypost",
196 "delivery_days": 2,
197 "delivery_date": null,
198 "delivery_date_guaranteed": false,
199 "est_delivery_days": 2,
200 "shipment_id": "shp_597ccf75eb5f441282d22199e802474b",
201 "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
202 },
203 "tracker": {
204 "id": "trk_02b25bf407344158a5016a467405fca8",
205 "object": "Tracker",
206 "mode": "test",
207 "tracking_code": "9405500208303109884199",
208 "status": "pre_transit",
209 "status_detail": "status_update",
210 "created_at": "2025-05-09T20:40:15Z",
211 "updated_at": "2025-05-09T20:40:15Z",
212 "signed_by": null,
213 "weight": null,
214 "est_delivery_date": "2025-05-09T20:40:15Z",
215 "shipment_id": "shp_597ccf75eb5f441282d22199e802474b",
216 "carrier": "USPS",
217 "tracking_details": [
218 {
219 "object": "TrackingDetail",
220 "message": "Pre-Shipment Info Sent to USPS",
221 "description": "",
222 "status": "pre_transit",
223 "status_detail": "status_update",
224 "datetime": "2025-04-09T20:40:15Z",
225 "source": "USPS",
226 "carrier_code": "",
227 "tracking_location": {
228 "object": "TrackingLocation",
229 "city": null,
230 "state": null,
231 "country": null,
232 "zip": null
233 },
234 "est_delivery_date": null
235 },
236 {
237 "object": "TrackingDetail",
238 "message": "Shipping Label Created",
239 "description": "",
240 "status": "pre_transit",
241 "status_detail": "status_update",
242 "datetime": "2025-04-10T09:17:15Z",
243 "source": "USPS",
244 "carrier_code": "",
245 "tracking_location": {
246 "object": "TrackingLocation",
247 "city": "HOUSTON",
248 "state": "TX",
249 "country": null,
250 "zip": "77063"
251 },
252 "est_delivery_date": null
253 }
254 ],
255 "fees": [],
256 "carrier_detail": {
257 "object": "CarrierDetail",
258 "service": "First-Class Package Service",
259 "container_type": null,
260 "est_delivery_date_local": null,
261 "est_delivery_time_local": null,
262 "origin_location": "HOUSTON TX, 77001",
263 "origin_tracking_location": {
264 "object": "TrackingLocation",
265 "city": "HOUSTON",
266 "state": "TX",
267 "country": null,
268 "zip": "77063"
269 },
270 "destination_location": "CHARLESTON SC, 29401",
271 "destination_tracking_location": null,
272 "guaranteed_delivery_date": null,
273 "alternate_identifier": null,
274 "initial_delivery_attempt": null
275 },
276 "public_url": "https://track.easypost.com/djE6dHJrXzAyYjI1YmY0MDczNDQxNThhNTAxNmE0Njc0MDVmY2E4"
277 },
278 "to_address": {
279 "id": "adr_cf672fea2d1511f0ba3d3cecef1b359e",
280 "object": "Address",
281 "created_at": "2025-05-09T20:40:14+00:00",
282 "updated_at": "2025-05-09T20:40:14+00:00",
283 "name": "DR. STEVE BRULE",
284 "company": null,
285 "street1": "179 N HARBOR DR",
286 "street2": null,
287 "city": "REDONDO BEACH",
288 "state": "CA",
289 "zip": "90277-2506",
290 "country": "US",
291 "phone": "8573875756",
292 "email": "DR_STEVE_BRULE@GMAIL.COM",
293 "mode": "test",
294 "carrier_facility": null,
295 "residential": false,
296 "federal_tax_id": null,
297 "state_tax_id": null,
298 "verifications": {
299 "zip4": {
300 "success": true,
301 "errors": [],
302 "details": null
303 },
304 "delivery": {
305 "success": true,
306 "errors": [],
307 "details": {
308 "latitude": 33.8436,
309 "longitude": -118.39177,
310 "time_zone": "America/Los_Angeles"
311 }
312 }
313 }
314 },
315 "usps_zone": 4,
316 "return_address": {
317 "id": "adr_cf698f942d1511f0ba403cecef1b359e",
318 "object": "Address",
319 "created_at": "2025-05-09T20:40:14+00:00",
320 "updated_at": "2025-05-09T20:40:14+00:00",
321 "name": "EasyPost",
322 "company": null,
323 "street1": "417 Montgomery Street",
324 "street2": "5th Floor",
325 "city": "San Francisco",
326 "state": "CA",
327 "zip": "94104",
328 "country": "US",
329 "phone": "4153334445",
330 "email": "support@easypost.com",
331 "mode": "test",
332 "carrier_facility": null,
333 "residential": null,
334 "federal_tax_id": null,
335 "state_tax_id": null,
336 "verifications": {}
337 },
338 "buyer_address": {
339 "id": "adr_cf672fea2d1511f0ba3d3cecef1b359e",
340 "object": "Address",
341 "created_at": "2025-05-09T20:40:14+00:00",
342 "updated_at": "2025-05-09T20:40:14+00:00",
343 "name": "DR. STEVE BRULE",
344 "company": null,
345 "street1": "179 N HARBOR DR",
346 "street2": null,
347 "city": "REDONDO BEACH",
348 "state": "CA",
349 "zip": "90277-2506",
350 "country": "US",
351 "phone": "8573875756",
352 "email": "DR_STEVE_BRULE@GMAIL.COM",
353 "mode": "test",
354 "carrier_facility": null,
355 "residential": false,
356 "federal_tax_id": null,
357 "state_tax_id": null,
358 "verifications": {
359 "zip4": {
360 "success": true,
361 "errors": [],
362 "details": null
363 },
364 "delivery": {
365 "success": true,
366 "errors": [],
367 "details": {
368 "latitude": 33.8436,
369 "longitude": -118.39177,
370 "time_zone": "America/Los_Angeles"
371 }
372 }
373 }
374 },
375 "forms": [],
376 "fees": [
377 {
378 "object": "Fee",
379 "type": "PostageFee",
380 "amount": "11.01000",
381 "charged": true,
382 "refunded": false
383 }
384 ],
385 "object": "Shipment"
386}