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 "created_at": "2024-01-24T00:07:25Z",
3 "is_return": true,
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": null,
16 "updated_at": "2024-01-24T00:07:25Z",
17 "batch_id": null,
18 "batch_status": null,
19 "batch_message": null,
20 "customs_info": {
21 "id": "cstinfo_75b9d86bcced4df4a90d971d79467395",
22 "object": "CustomsInfo",
23 "created_at": "2024-01-24T00:07:25Z",
24 "updated_at": "2024-01-24T00:07:25Z",
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_28713b4da6c442c59fc2643c27e68fbc",
38 "object": "CustomsItem",
39 "created_at": "2024-01-24T00:07:25Z",
40 "updated_at": "2024-01-24T00:07:25Z",
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_8dcc8d20ba4c11eeb60eac1f6bc539aa",
58 "object": "Address",
59 "created_at": "2024-01-24T00:07:25+00:00",
60 "updated_at": "2024-01-24T00:07:25+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_f5c724b686f5426e86572e0c6ae2eca3",
82 "object": "Parcel",
83 "created_at": "2024-01-24T00:07:25Z",
84 "updated_at": "2024-01-24T00:07:25Z",
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": null,
93 "rates": [
94 {
95 "id": "rate_a5473958bf84407d98729d6a0ae57a50",
96 "object": "Rate",
97 "created_at": "2024-01-24T00:07:25Z",
98 "updated_at": "2024-01-24T00:07:25Z",
99 "mode": "test",
100 "service": "Express",
101 "carrier": "USPS",
102 "rate": "49.60",
103 "currency": "USD",
104 "retail_rate": "57.40",
105 "retail_currency": "USD",
106 "list_rate": "49.60",
107 "list_currency": "USD",
108 "billing_type": "easypost",
109 "delivery_days": null,
110 "delivery_date": null,
111 "delivery_date_guaranteed": false,
112 "est_delivery_days": null,
113 "shipment_id": "shp_d270335b7bf846b3b03b67df7c181d6f",
114 "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
115 },
116 {
117 "id": "rate_cf8d03f7b5054a52a6f7e87a8f38bf86",
118 "object": "Rate",
119 "created_at": "2024-01-24T00:07:25Z",
120 "updated_at": "2024-01-24T00:07:25Z",
121 "mode": "test",
122 "service": "Priority",
123 "carrier": "USPS",
124 "rate": "7.33",
125 "currency": "USD",
126 "retail_rate": "15.20",
127 "retail_currency": "USD",
128 "list_rate": "10.89",
129 "list_currency": "USD",
130 "billing_type": "easypost",
131 "delivery_days": 2,
132 "delivery_date": null,
133 "delivery_date_guaranteed": false,
134 "est_delivery_days": 2,
135 "shipment_id": "shp_d270335b7bf846b3b03b67df7c181d6f",
136 "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
137 },
138 {
139 "id": "rate_51439cb11b9b4aa9b2de79bfc24fcae8",
140 "object": "Rate",
141 "created_at": "2024-01-24T00:07:25Z",
142 "updated_at": "2024-01-24T00:07:25Z",
143 "mode": "test",
144 "service": "GroundAdvantage",
145 "carrier": "USPS",
146 "rate": "6.79",
147 "currency": "USD",
148 "retail_rate": "13.15",
149 "retail_currency": "USD",
150 "list_rate": "9.41",
151 "list_currency": "USD",
152 "billing_type": "easypost",
153 "delivery_days": 3,
154 "delivery_date": null,
155 "delivery_date_guaranteed": false,
156 "est_delivery_days": 3,
157 "shipment_id": "shp_d270335b7bf846b3b03b67df7c181d6f",
158 "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
159 },
160 {
161 "id": "rate_45e9d6f024724c47822543032841289f",
162 "object": "Rate",
163 "created_at": "2024-01-24T00:07:25Z",
164 "updated_at": "2024-01-24T00:07:25Z",
165 "mode": "test",
166 "service": "First",
167 "carrier": "USPS",
168 "rate": "6.79",
169 "currency": "USD",
170 "retail_rate": "13.15",
171 "retail_currency": "USD",
172 "list_rate": "9.41",
173 "list_currency": "USD",
174 "billing_type": "easypost",
175 "delivery_days": 3,
176 "delivery_date": null,
177 "delivery_date_guaranteed": false,
178 "est_delivery_days": 3,
179 "shipment_id": "shp_d270335b7bf846b3b03b67df7c181d6f",
180 "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
181 },
182 {
183 "id": "rate_45ac4cce2b18400ea50e0f330f74b430",
184 "object": "Rate",
185 "created_at": "2024-01-24T00:07:25Z",
186 "updated_at": "2024-01-24T00:07:25Z",
187 "mode": "test",
188 "service": "ParcelSelect",
189 "carrier": "USPS",
190 "rate": "6.79",
191 "currency": "USD",
192 "retail_rate": "13.15",
193 "retail_currency": "USD",
194 "list_rate": "9.41",
195 "list_currency": "USD",
196 "billing_type": "easypost",
197 "delivery_days": 3,
198 "delivery_date": null,
199 "delivery_date_guaranteed": false,
200 "est_delivery_days": 3,
201 "shipment_id": "shp_d270335b7bf846b3b03b67df7c181d6f",
202 "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
203 }
204 ],
205 "refund_status": null,
206 "scan_form": null,
207 "selected_rate": null,
208 "tracker": null,
209 "to_address": {
210 "id": "adr_8dc57048ba4c11eea6e33cecef1b359e",
211 "object": "Address",
212 "created_at": "2024-01-24T00:07:25+00:00",
213 "updated_at": "2024-01-24T00:07:25+00:00",
214 "name": "Dr. Steve Brule",
215 "company": null,
216 "street1": "179 N Harbor Dr",
217 "street2": null,
218 "city": "Redondo Beach",
219 "state": "CA",
220 "zip": "90277",
221 "country": "US",
222 "phone": "8573875756",
223 "email": "dr_steve_brule@gmail.com",
224 "mode": "test",
225 "carrier_facility": null,
226 "residential": null,
227 "federal_tax_id": null,
228 "state_tax_id": null,
229 "verifications": {}
230 },
231 "usps_zone": 4,
232 "return_address": {
233 "id": "adr_8dcc8d20ba4c11eeb60eac1f6bc539aa",
234 "object": "Address",
235 "created_at": "2024-01-24T00:07:25+00:00",
236 "updated_at": "2024-01-24T00:07:25+00:00",
237 "name": "EasyPost",
238 "company": null,
239 "street1": "417 Montgomery Street",
240 "street2": "5th Floor",
241 "city": "San Francisco",
242 "state": "CA",
243 "zip": "94104",
244 "country": "US",
245 "phone": "4153334445",
246 "email": "support@easypost.com",
247 "mode": "test",
248 "carrier_facility": null,
249 "residential": null,
250 "federal_tax_id": null,
251 "state_tax_id": null,
252 "verifications": {}
253 },
254 "buyer_address": {
255 "id": "adr_8dc57048ba4c11eea6e33cecef1b359e",
256 "object": "Address",
257 "created_at": "2024-01-24T00:07:25+00:00",
258 "updated_at": "2024-01-24T00:07:25+00:00",
259 "name": "Dr. Steve Brule",
260 "company": null,
261 "street1": "179 N Harbor Dr",
262 "street2": null,
263 "city": "Redondo Beach",
264 "state": "CA",
265 "zip": "90277",
266 "country": "US",
267 "phone": "8573875756",
268 "email": "dr_steve_brule@gmail.com",
269 "mode": "test",
270 "carrier_facility": null,
271 "residential": null,
272 "federal_tax_id": null,
273 "state_tax_id": null,
274 "verifications": {}
275 },
276 "forms": [],
277 "fees": [],
278 "id": "shp_d270335b7bf846b3b03b67df7c181d6f",
279 "object": "Shipment"
280}