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.
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"
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.
Refunds created very shortly after a label is generated may be improperly flagged as invalid, but you may retry a refund with the "rejected" status
by submitting the same request again.
Carriers that are bill-on-scan tend to have refunds attempts return as "not_applicable", which will not change with multiple retries.
1curl -X POST https://api.easypost.com/v2/shipments/shp_.../refund \
2 -u "EASYPOST_API_KEY":
1{
2 "created_at": "2024-01-24T00:36:23Z",
3 "is_return": false,
4 "messages": [],
5 "mode": "test",
6 "options": {
7 "currency": "USD",
8 "payment": {
9 "type": "SENDER"
10 },
11 "date_advance": 0
12 },
13 "reference": null,
14 "status": "unknown",
15 "tracking_code": "9405500207552011818490",
16 "updated_at": "2024-01-24T00:36:24Z",
17 "batch_id": null,
18 "batch_status": null,
19 "batch_message": null,
20 "customs_info": {
21 "id": "cstinfo_eee83608742840b7aa1c20c38f069cb1",
22 "object": "CustomsInfo",
23 "created_at": "2024-01-24T00:36:23Z",
24 "updated_at": "2024-01-24T00:36:23Z",
25 "contents_explanation": "",
26 "contents_type": "merchandise",
27 "customs_certify": true,
28 "customs_signer": "Steve Brule",
29 "eel_pfc": "NOEEI 30.37(a)",
30 "non_delivery_option": "return",
31 "restriction_comments": null,
32 "restriction_type": "none",
33 "mode": "test",
34 "declaration": null,
35 "customs_items": [
36 {
37 "id": "cstitem_f8398fb53c8e4efe9df5968ce2d2d449",
38 "object": "CustomsItem",
39 "created_at": "2024-01-24T00:36:23Z",
40 "updated_at": "2024-01-24T00:36:23Z",
41 "description": "T-shirt",
42 "hs_tariff_number": "123456",
43 "origin_country": "US",
44 "quantity": 1,
45 "value": "10.0",
46 "weight": 5.0,
47 "code": "123",
48 "mode": "test",
49 "manufacturer": null,
50 "currency": null,
51 "eccn": null,
52 "printed_commodity_identifier": null
53 }
54 ]
55 },
56 "from_address": {
57 "id": "adr_997cf4e0ba5011eeac3bac1f6bc53342",
58 "object": "Address",
59 "created_at": "2024-01-24T00:36:23+00:00",
60 "updated_at": "2024-01-24T00:36:23+00:00",
61 "name": "EasyPost",
62 "company": null,
63 "street1": "417 Montgomery Street",
64 "street2": "5th Floor",
65 "city": "San Francisco",
66 "state": "CA",
67 "zip": "94104",
68 "country": "US",
69 "phone": "4153334445",
70 "email": "support@easypost.com",
71 "mode": "test",
72 "carrier_facility": null,
73 "residential": null,
74 "federal_tax_id": null,
75 "state_tax_id": null,
76 "verifications": {}
77 },
78 "insurance": null,
79 "order_id": null,
80 "parcel": {
81 "id": "prcl_a019a6b39a544a8590527d22522e4685",
82 "object": "Parcel",
83 "created_at": "2024-01-24T00:36:23Z",
84 "updated_at": "2024-01-24T00:36:23Z",
85 "length": 20.2,
86 "width": 10.9,
87 "height": 5.0,
88 "predefined_package": null,
89 "weight": 65.9,
90 "mode": "test"
91 },
92 "postage_label": {
93 "object": "PostageLabel",
94 "id": "pl_da441fc128ec4987b792a759df9c2f48",
95 "created_at": "2024-01-24T00:36:23Z",
96 "updated_at": "2024-01-24T00:36:24Z",
97 "date_advance": 0,
98 "integrated_form": "none",
99 "label_date": "2024-01-24T00:36:23Z",
100 "label_resolution": 300,
101 "label_size": "4x6",
102 "label_type": "default",
103 "label_file_type": "image/png",
104 "label_url": "https://easypost-files.s3.us-west-2.amazonaws.com/files/postage_label/20240124/e822df92b132b44139ac11182aaa78181c.png",
105 "label_pdf_url": null,
106 "label_zpl_url": null,
107 "label_epl2_url": null,
108 "label_file": null
109 },
110 "rates": [
111 {
112 "id": "rate_70bf8e810a364331a5bf89b1fbee27dd",
113 "object": "Rate",
114 "created_at": "2024-01-24T00:36:23Z",
115 "updated_at": "2024-01-24T00:36:23Z",
116 "mode": "test",
117 "service": "GroundAdvantage",
118 "carrier": "USPS",
119 "rate": "6.79",
120 "currency": "USD",
121 "retail_rate": "13.15",
122 "retail_currency": "USD",
123 "list_rate": "9.41",
124 "list_currency": "USD",
125 "billing_type": "easypost",
126 "delivery_days": 3,
127 "delivery_date": null,
128 "delivery_date_guaranteed": false,
129 "est_delivery_days": 3,
130 "shipment_id": "shp_3d349554446b4d85a59a367bda4e16f1",
131 "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
132 },
133 {
134 "id": "rate_5bd8322e638f48f7a0a9546773e80ea1",
135 "object": "Rate",
136 "created_at": "2024-01-24T00:36:23Z",
137 "updated_at": "2024-01-24T00:36:23Z",
138 "mode": "test",
139 "service": "First",
140 "carrier": "USPS",
141 "rate": "6.79",
142 "currency": "USD",
143 "retail_rate": "13.15",
144 "retail_currency": "USD",
145 "list_rate": "9.41",
146 "list_currency": "USD",
147 "billing_type": "easypost",
148 "delivery_days": 3,
149 "delivery_date": null,
150 "delivery_date_guaranteed": false,
151 "est_delivery_days": 3,
152 "shipment_id": "shp_3d349554446b4d85a59a367bda4e16f1",
153 "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
154 },
155 {
156 "id": "rate_ae9accce625e4dbea50caa5316a718f4",
157 "object": "Rate",
158 "created_at": "2024-01-24T00:36:23Z",
159 "updated_at": "2024-01-24T00:36:23Z",
160 "mode": "test",
161 "service": "ParcelSelect",
162 "carrier": "USPS",
163 "rate": "6.79",
164 "currency": "USD",
165 "retail_rate": "13.15",
166 "retail_currency": "USD",
167 "list_rate": "9.41",
168 "list_currency": "USD",
169 "billing_type": "easypost",
170 "delivery_days": 3,
171 "delivery_date": null,
172 "delivery_date_guaranteed": false,
173 "est_delivery_days": 3,
174 "shipment_id": "shp_3d349554446b4d85a59a367bda4e16f1",
175 "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
176 },
177 {
178 "id": "rate_37f9982f38274b85a17ac4269eb40829",
179 "object": "Rate",
180 "created_at": "2024-01-24T00:36:23Z",
181 "updated_at": "2024-01-24T00:36:23Z",
182 "mode": "test",
183 "service": "Express",
184 "carrier": "USPS",
185 "rate": "49.60",
186 "currency": "USD",
187 "retail_rate": "57.40",
188 "retail_currency": "USD",
189 "list_rate": "49.60",
190 "list_currency": "USD",
191 "billing_type": "easypost",
192 "delivery_days": null,
193 "delivery_date": null,
194 "delivery_date_guaranteed": false,
195 "est_delivery_days": null,
196 "shipment_id": "shp_3d349554446b4d85a59a367bda4e16f1",
197 "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
198 },
199 {
200 "id": "rate_a8cc5650c3dd49328709c7b3ad010908",
201 "object": "Rate",
202 "created_at": "2024-01-24T00:36:23Z",
203 "updated_at": "2024-01-24T00:36:23Z",
204 "mode": "test",
205 "service": "Priority",
206 "carrier": "USPS",
207 "rate": "7.33",
208 "currency": "USD",
209 "retail_rate": "15.20",
210 "retail_currency": "USD",
211 "list_rate": "10.89",
212 "list_currency": "USD",
213 "billing_type": "easypost",
214 "delivery_days": 2,
215 "delivery_date": null,
216 "delivery_date_guaranteed": false,
217 "est_delivery_days": 2,
218 "shipment_id": "shp_3d349554446b4d85a59a367bda4e16f1",
219 "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
220 }
221 ],
222 "refund_status": "submitted",
223 "scan_form": null,
224 "selected_rate": {
225 "id": "rate_a8cc5650c3dd49328709c7b3ad010908",
226 "object": "Rate",
227 "created_at": "2024-01-24T00:36:23Z",
228 "updated_at": "2024-01-24T00:36:23Z",
229 "mode": "test",
230 "service": "Priority",
231 "carrier": "USPS",
232 "rate": "7.33",
233 "currency": "USD",
234 "retail_rate": "15.20",
235 "retail_currency": "USD",
236 "list_rate": "10.89",
237 "list_currency": "USD",
238 "billing_type": "easypost",
239 "delivery_days": 2,
240 "delivery_date": null,
241 "delivery_date_guaranteed": false,
242 "est_delivery_days": 2,
243 "shipment_id": "shp_3d349554446b4d85a59a367bda4e16f1",
244 "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
245 },
246 "tracker": {
247 "id": "trk_7adde026444941eb83df3c483eeaae24",
248 "object": "Tracker",
249 "mode": "test",
250 "tracking_code": "9405500207552011818490",
251 "status": "pre_transit",
252 "status_detail": "status_update",
253 "created_at": "2024-01-24T00:36:24Z",
254 "updated_at": "2024-01-24T00:36:24Z",
255 "signed_by": null,
256 "weight": null,
257 "est_delivery_date": "2024-01-24T00:36:24Z",
258 "shipment_id": "shp_3d349554446b4d85a59a367bda4e16f1",
259 "carrier": "USPS",
260 "tracking_details": [
261 {
262 "object": "TrackingDetail",
263 "message": "Pre-Shipment Info Sent to USPS",
264 "description": "",
265 "status": "pre_transit",
266 "status_detail": "status_update",
267 "datetime": "2023-12-24T00:36:24Z",
268 "source": "USPS",
269 "carrier_code": "",
270 "tracking_location": {
271 "object": "TrackingLocation",
272 "city": null,
273 "state": null,
274 "country": null,
275 "zip": null
276 }
277 },
278 {
279 "object": "TrackingDetail",
280 "message": "Shipping Label Created",
281 "description": "",
282 "status": "pre_transit",
283 "status_detail": "status_update",
284 "datetime": "2023-12-24T13:13:24Z",
285 "source": "USPS",
286 "carrier_code": "",
287 "tracking_location": {
288 "object": "TrackingLocation",
289 "city": "HOUSTON",
290 "state": "TX",
291 "country": null,
292 "zip": "77063"
293 }
294 }
295 ],
296 "fees": [],
297 "carrier_detail": {
298 "object": "CarrierDetail",
299 "service": "First-Class Package Service",
300 "container_type": null,
301 "est_delivery_date_local": null,
302 "est_delivery_time_local": null,
303 "origin_location": "HOUSTON TX, 77001",
304 "origin_tracking_location": {
305 "object": "TrackingLocation",
306 "city": "HOUSTON",
307 "state": "TX",
308 "country": null,
309 "zip": "77063"
310 },
311 "destination_location": "CHARLESTON SC, 29401",
312 "destination_tracking_location": null,
313 "guaranteed_delivery_date": null,
314 "alternate_identifier": null,
315 "initial_delivery_attempt": null
316 },
317 "public_url": "https://track.easypost.com/djE6dHJrXzdhZGRlMDI2NDQ0OTQxZWI4M2RmM2M0ODNlZWFhZTI0"
318 },
319 "to_address": {
320 "id": "adr_997b2527ba5011eeac3aac1f6bc53342",
321 "object": "Address",
322 "created_at": "2024-01-24T00:36:23+00:00",
323 "updated_at": "2024-01-24T00:36:23+00:00",
324 "name": "DR. STEVE BRULE",
325 "company": null,
326 "street1": "179 N HARBOR DR",
327 "street2": null,
328 "city": "REDONDO BEACH",
329 "state": "CA",
330 "zip": "90277-2506",
331 "country": "US",
332 "phone": "8573875756",
333 "email": "DR_STEVE_BRULE@GMAIL.COM",
334 "mode": "test",
335 "carrier_facility": null,
336 "residential": false,
337 "federal_tax_id": null,
338 "state_tax_id": null,
339 "verifications": {
340 "zip4": {
341 "success": true,
342 "errors": [],
343 "details": null
344 },
345 "delivery": {
346 "success": true,
347 "errors": [],
348 "details": {
349 "latitude": 33.8436,
350 "longitude": -118.39177,
351 "time_zone": "America/Los_Angeles"
352 }
353 }
354 }
355 },
356 "usps_zone": 4,
357 "return_address": {
358 "id": "adr_997cf4e0ba5011eeac3bac1f6bc53342",
359 "object": "Address",
360 "created_at": "2024-01-24T00:36:23+00:00",
361 "updated_at": "2024-01-24T00:36:23+00:00",
362 "name": "EasyPost",
363 "company": null,
364 "street1": "417 Montgomery Street",
365 "street2": "5th Floor",
366 "city": "San Francisco",
367 "state": "CA",
368 "zip": "94104",
369 "country": "US",
370 "phone": "4153334445",
371 "email": "support@easypost.com",
372 "mode": "test",
373 "carrier_facility": null,
374 "residential": null,
375 "federal_tax_id": null,
376 "state_tax_id": null,
377 "verifications": {}
378 },
379 "buyer_address": {
380 "id": "adr_997b2527ba5011eeac3aac1f6bc53342",
381 "object": "Address",
382 "created_at": "2024-01-24T00:36:23+00:00",
383 "updated_at": "2024-01-24T00:36:23+00:00",
384 "name": "DR. STEVE BRULE",
385 "company": null,
386 "street1": "179 N HARBOR DR",
387 "street2": null,
388 "city": "REDONDO BEACH",
389 "state": "CA",
390 "zip": "90277-2506",
391 "country": "US",
392 "phone": "8573875756",
393 "email": "DR_STEVE_BRULE@GMAIL.COM",
394 "mode": "test",
395 "carrier_facility": null,
396 "residential": false,
397 "federal_tax_id": null,
398 "state_tax_id": null,
399 "verifications": {
400 "zip4": {
401 "success": true,
402 "errors": [],
403 "details": null
404 },
405 "delivery": {
406 "success": true,
407 "errors": [],
408 "details": {
409 "latitude": 33.8436,
410 "longitude": -118.39177,
411 "time_zone": "America/Los_Angeles"
412 }
413 }
414 }
415 },
416 "forms": [],
417 "fees": [
418 {
419 "object": "Fee",
420 "type": "LabelFee",
421 "amount": "0.00000",
422 "charged": true,
423 "refunded": false
424 },
425 {
426 "object": "Fee",
427 "type": "PostageFee",
428 "amount": "7.33000",
429 "charged": true,
430 "refunded": false
431 }
432 ],
433 "id": "shp_3d349554446b4d85a59a367bda4e16f1",
434 "object": "Shipment"
435}