Return
If you are shipping merchandise or other frequently-returned products, you may wish to generate return labels to include with your shipment, for you customer's convenience. EasyPost offers a simple way to submit the same parameters as your initial shipment, but with an additional flag set, that will generate you a return label to receive any return shipments at your original from address.
It's important for some carriers, with different return billing, to
specify a return label even if it's not a return label for an earlier Shipment.
If doing more than 10,000 USPS returns in a year, please contact EasyPost for the USPS scan-based return program, which we also offer.
Endpoints
You can easily create return labels. All you need to do is set the
is_return parameter to true, leave the addresses the same
as the initial Shipment's creation request and we
switch the to_address and from_address for
the return Shipment.
POST /
1curl -X POST https://api.easypost.com/v2/shipments \
2 -u "EASYPOST_API_KEY": \
3 -H 'Content-Type: application/json' \
4 -d '{
5 "shipment": {
6 "to_address": {
7 "name": "Dr. Steve Brule",
8 "street1": "179 N Harbor Dr",
9 "city": "Redondo Beach",
10 "state": "CA",
11 "zip": "90277",
12 "country": "US",
13 "phone": "8573875756",
14 "email": "dr_steve_brule@gmail.com"
15 },
16 "from_address": {
17 "name": "EasyPost",
18 "street1": "417 Montgomery Street",
19 "street2": "5th Floor",
20 "city": "San Francisco",
21 "state": "CA",
22 "zip": "94104",
23 "country": "US",
24 "phone": "4153334445",
25 "email": "support@easypost.com"
26 },
27 "parcel": {
28 "length": "20.2",
29 "width": "10.9",
30 "height": "5",
31 "weight": "65.9"
32 },
33 "is_return": true
34 }
35 }'Response
1{
2 "id": "shp_18efc5c59c4b4bc598eb47070948cec8",
3 "created_at": "2025-05-09T20:40:03Z",
4 "is_return": true,
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": null,
17 "updated_at": "2025-05-09T20:40:03Z",
18 "batch_id": null,
19 "batch_status": null,
20 "batch_message": null,
21 "customs_info": {
22 "id": "cstinfo_bf9f3daf888b45d8a3d9f10ae4442066",
23 "object": "CustomsInfo",
24 "created_at": "2025-05-09T20:40:03Z",
25 "updated_at": "2025-05-09T20:40:03Z",
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_016eaf20de854811afcc38b3de173b61",
39 "object": "CustomsItem",
40 "created_at": "2025-05-09T20:40:03Z",
41 "updated_at": "2025-05-09T20:40:03Z",
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_c89405492d1511f09304ac1f6bc539aa",
59 "object": "Address",
60 "created_at": "2025-05-09T20:40:03+00:00",
61 "updated_at": "2025-05-09T20:40:03+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_c671988089da4d0e8089f6e0594f3166",
83 "object": "Parcel",
84 "created_at": "2025-05-09T20:40:03Z",
85 "updated_at": "2025-05-09T20:40:03Z",
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": null,
94 "rates": [
95 {
96 "id": "rate_a182936e829f4d22aa0455b932055384",
97 "object": "Rate",
98 "created_at": "2025-05-09T20:40:03Z",
99 "updated_at": "2025-05-09T20:40:03Z",
100 "mode": "test",
101 "service": "Express",
102 "carrier": "USPS",
103 "rate": "51.20",
104 "currency": "USD",
105 "retail_rate": "59.25",
106 "retail_currency": "USD",
107 "list_rate": "51.20",
108 "list_currency": "USD",
109 "billing_type": "easypost",
110 "delivery_days": 2,
111 "delivery_date": null,
112 "delivery_date_guaranteed": false,
113 "est_delivery_days": 2,
114 "shipment_id": "shp_18efc5c59c4b4bc598eb47070948cec8",
115 "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
116 },
117 {
118 "id": "rate_129ccaa93fd143fdbc1a87d166c60fbf",
119 "object": "Rate",
120 "created_at": "2025-05-09T20:40:03Z",
121 "updated_at": "2025-05-09T20:40:03Z",
122 "mode": "test",
123 "service": "Priority",
124 "carrier": "USPS",
125 "rate": "11.01",
126 "currency": "USD",
127 "retail_rate": "15.40",
128 "retail_currency": "USD",
129 "list_rate": "11.01",
130 "list_currency": "USD",
131 "billing_type": "easypost",
132 "delivery_days": 3,
133 "delivery_date": null,
134 "delivery_date_guaranteed": false,
135 "est_delivery_days": 3,
136 "shipment_id": "shp_18efc5c59c4b4bc598eb47070948cec8",
137 "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
138 },
139 {
140 "id": "rate_e77cbaf75acc4ac2acf81cd450fa15d6",
141 "object": "Rate",
142 "created_at": "2025-05-09T20:40:03Z",
143 "updated_at": "2025-05-09T20:40:03Z",
144 "mode": "test",
145 "service": "GroundAdvantage",
146 "carrier": "USPS",
147 "rate": "8.20",
148 "currency": "USD",
149 "retail_rate": "13.85",
150 "retail_currency": "USD",
151 "list_rate": "9.74",
152 "list_currency": "USD",
153 "billing_type": "easypost",
154 "delivery_days": 3,
155 "delivery_date": null,
156 "delivery_date_guaranteed": false,
157 "est_delivery_days": 3,
158 "shipment_id": "shp_18efc5c59c4b4bc598eb47070948cec8",
159 "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
160 }
161 ],
162 "refund_status": null,
163 "scan_form": null,
164 "selected_rate": null,
165 "tracker": null,
166 "to_address": {
167 "id": "adr_c89186f82d1511f0ba54ac1f6bc539ae",
168 "object": "Address",
169 "created_at": "2025-05-09T20:40:03+00:00",
170 "updated_at": "2025-05-09T20:40:03+00:00",
171 "name": "Dr. Steve Brule",
172 "company": null,
173 "street1": "179 N Harbor Dr",
174 "street2": null,
175 "city": "Redondo Beach",
176 "state": "CA",
177 "zip": "90277",
178 "country": "US",
179 "phone": "8573875756",
180 "email": "dr_steve_brule@gmail.com",
181 "mode": "test",
182 "carrier_facility": null,
183 "residential": null,
184 "federal_tax_id": null,
185 "state_tax_id": null,
186 "verifications": {}
187 },
188 "usps_zone": 4,
189 "return_address": {
190 "id": "adr_c89405492d1511f09304ac1f6bc539aa",
191 "object": "Address",
192 "created_at": "2025-05-09T20:40:03+00:00",
193 "updated_at": "2025-05-09T20:40:03+00:00",
194 "name": "EasyPost",
195 "company": null,
196 "street1": "417 Montgomery Street",
197 "street2": "5th Floor",
198 "city": "San Francisco",
199 "state": "CA",
200 "zip": "94104",
201 "country": "US",
202 "phone": "4153334445",
203 "email": "support@easypost.com",
204 "mode": "test",
205 "carrier_facility": null,
206 "residential": null,
207 "federal_tax_id": null,
208 "state_tax_id": null,
209 "verifications": {}
210 },
211 "buyer_address": {
212 "id": "adr_c89186f82d1511f0ba54ac1f6bc539ae",
213 "object": "Address",
214 "created_at": "2025-05-09T20:40:03+00:00",
215 "updated_at": "2025-05-09T20:40:03+00:00",
216 "name": "Dr. Steve Brule",
217 "company": null,
218 "street1": "179 N Harbor Dr",
219 "street2": null,
220 "city": "Redondo Beach",
221 "state": "CA",
222 "zip": "90277",
223 "country": "US",
224 "phone": "8573875756",
225 "email": "dr_steve_brule@gmail.com",
226 "mode": "test",
227 "carrier_facility": null,
228 "residential": null,
229 "federal_tax_id": null,
230 "state_tax_id": null,
231 "verifications": {}
232 },
233 "forms": [],
234 "fees": [],
235 "object": "Shipment"
236}