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 "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}