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": "[email protected]",
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": "[email protected]",
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": "[email protected]",
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": "[email protected]",
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}