Form

After a Shipment is created, you can create various associated Form objects for that Shipment, such as a return packing slip, QR codes, and other international shipping forms. For more information about how to use forms with your shipments, please check our forms guide.

Forms that may be returned with Shipment objects depending on the carrier and data passed:

cn22
cod_return_label
commercial_invoice
high_value_report
nafta_certificate_of_origin
order_summary

Forms that can be created after a Shipment has been bought:

commercial_invoice
label_qr_code
return_packing_slip
rma_qr_code

Endpoints

POST

/shipments/:id/forms

Form object

string

Unique, begins with "form_"

object

string

"Form"

mode

string

"test" or "production"

form_type

string

The type of form. Possible values:

"cn22"
"cod_return_label"
"commercial_invoice"
"high_value_report"
"label_qr_code"
"nafta_certificate_of_origin"
"order_summary"
"return_packing_slip"
"rma_qr_code"

form_url

string

The URL from which the form can be downloaded

submitted_electronically

boolean

If EasyPost has submitted the form to the carrier on behalf of the user

created_at

datetime

When the Form was created

updated_at

datetime

When the Form was last updated

Form Object

{
  "object": "Form",
  "id": "form_c7d83834b45544399bf704c468df06b6",
  "created_at": "2025-05-09T20:39:21Z",
  "updated_at": "2025-05-09T20:39:21Z",
  "mode": "test",
  "form_type": "return_packing_slip",
  "form_url": "https://easypost-files.s3-us-west-2.amazonaws.com/files/form/20250509/827694e0c57149079d691ac3fb85e2b1.pdf",
  "submitted_electronically": null
}

Create Form

Please see forms guide for request parameters.

POST /shipments/:id/forms

1# type always required
2# all other elements differ based on form type
3curl -X POST https://api.easypost.com/v2/shipments/shp_.../forms \
4  -u "EASYPOST_API_KEY": \
5  -H 'Content-Type: application/json' \
6  -d '{
7    "form": {
8        "type": "return_packing_slip",
9        "barcode": "RMA12345678900",
10        "line_items": [
11        {
12            "product": {
13                "title": "Square Reader",
14                "barcode": "855658003251"
15            },
16            "units": 8
17        }
18      ]
19    }
20  }'

Response

1{
2  "id": "shp_c1e2946bb3c84b13a383168190a0c7e4",
3  "created_at": "2025-05-09T20:39:20Z",
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": "9405500208303109884083",
17  "updated_at": "2025-05-09T20:39:20Z",
18  "batch_id": null,
19  "batch_status": null,
20  "batch_message": null,
21  "customs_info": {
22    "id": "cstinfo_93e983e34bd044d9ba941f01a59a5654",
23    "object": "CustomsInfo",
24    "created_at": "2025-05-09T20:39:20Z",
25    "updated_at": "2025-05-09T20:39:20Z",
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_6f7d78c129384937b830e0fc1ad245d7",
39        "object": "CustomsItem",
40        "created_at": "2025-05-09T20:39:20Z",
41        "updated_at": "2025-05-09T20:39:20Z",
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_af0074a72d1511f0aa27ac1f6bc539ae",
59    "object": "Address",
60    "created_at": "2025-05-09T20:39:20+00:00",
61    "updated_at": "2025-05-09T20:39:20+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_6a8fee5bf2a04f3d8b30efe1e28f0edf",
83    "object": "Parcel",
84    "created_at": "2025-05-09T20:39:20Z",
85    "updated_at": "2025-05-09T20:39:20Z",
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_14e14fa52a7c46a6ba6468724ee7e6e6",
96    "created_at": "2025-05-09T20:39:20Z",
97    "updated_at": "2025-05-09T20:39:20Z",
98    "date_advance": 0,
99    "integrated_form": "none",
100    "label_date": "2025-05-09T20:39:20Z",
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/e8e22a61dc0dd544f7803aec40ae2da05f.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_9a59180d1ac04c1e9d578575941728c3",
114      "object": "Rate",
115      "created_at": "2025-05-09T20:39:20Z",
116      "updated_at": "2025-05-09T20:39:20Z",
117      "mode": "test",
118      "service": "Express",
119      "carrier": "USPS",
120      "rate": "51.20",
121      "currency": "USD",
122      "retail_rate": "59.25",
123      "retail_currency": "USD",
124      "list_rate": "51.20",
125      "list_currency": "USD",
126      "billing_type": "easypost",
127      "delivery_days": 2,
128      "delivery_date": null,
129      "delivery_date_guaranteed": false,
130      "est_delivery_days": 2,
131      "shipment_id": "shp_c1e2946bb3c84b13a383168190a0c7e4",
132      "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
133    },
134    {
135      "id": "rate_1e8725994ca847299188a76543d1ee5c",
136      "object": "Rate",
137      "created_at": "2025-05-09T20:39:20Z",
138      "updated_at": "2025-05-09T20:39:20Z",
139      "mode": "test",
140      "service": "Priority",
141      "carrier": "USPS",
142      "rate": "11.01",
143      "currency": "USD",
144      "retail_rate": "15.40",
145      "retail_currency": "USD",
146      "list_rate": "11.01",
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_c1e2946bb3c84b13a383168190a0c7e4",
154      "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
155    },
156    {
157      "id": "rate_89e3dc281a4a4993aa4636b260f9bd74",
158      "object": "Rate",
159      "created_at": "2025-05-09T20:39:20Z",
160      "updated_at": "2025-05-09T20:39:20Z",
161      "mode": "test",
162      "service": "GroundAdvantage",
163      "carrier": "USPS",
164      "rate": "8.20",
165      "currency": "USD",
166      "retail_rate": "13.85",
167      "retail_currency": "USD",
168      "list_rate": "9.74",
169      "list_currency": "USD",
170      "billing_type": "easypost",
171      "delivery_days": 3,
172      "delivery_date": null,
173      "delivery_date_guaranteed": false,
174      "est_delivery_days": 3,
175      "shipment_id": "shp_c1e2946bb3c84b13a383168190a0c7e4",
176      "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
177    }
178  ],
179  "refund_status": null,
180  "scan_form": null,
181  "selected_rate": {
182    "id": "rate_1e8725994ca847299188a76543d1ee5c",
183    "object": "Rate",
184    "created_at": "2025-05-09T20:39:20Z",
185    "updated_at": "2025-05-09T20:39:20Z",
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_c1e2946bb3c84b13a383168190a0c7e4",
201    "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
202  },
203  "tracker": {
204    "id": "trk_266fa8e93fa54a408fd1a734054c7743",
205    "object": "Tracker",
206    "mode": "test",
207    "tracking_code": "9405500208303109884083",
208    "status": "pre_transit",
209    "status_detail": "status_update",
210    "created_at": "2025-05-09T20:39:21Z",
211    "updated_at": "2025-05-09T20:39:21Z",
212    "signed_by": null,
213    "weight": null,
214    "est_delivery_date": "2025-05-09T20:39:21Z",
215    "shipment_id": "shp_c1e2946bb3c84b13a383168190a0c7e4",
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:39:21Z",
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:16:21Z",
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/djE6dHJrXzI2NmZhOGU5M2ZhNTRhNDA4ZmQxYTczNDA1NGM3NzQz"
277  },
278  "to_address": {
279    "id": "adr_aefd9a212d1511f0aa26ac1f6bc539ae",
280    "object": "Address",
281    "created_at": "2025-05-09T20:39:20+00:00",
282    "updated_at": "2025-05-09T20:39:20+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": "DR_STEVE_BRULE@GMAIL.COM",
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_af0074a72d1511f0aa27ac1f6bc539ae",
318    "object": "Address",
319    "created_at": "2025-05-09T20:39:20+00:00",
320    "updated_at": "2025-05-09T20:39:20+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": "support@easypost.com",
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_aefd9a212d1511f0aa26ac1f6bc539ae",
340    "object": "Address",
341    "created_at": "2025-05-09T20:39:20+00:00",
342    "updated_at": "2025-05-09T20:39:20+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": "DR_STEVE_BRULE@GMAIL.COM",
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    {
377      "object": "Form",
378      "id": "form_c7d83834b45544399bf704c468df06b6",
379      "created_at": "2025-05-09T20:39:21Z",
380      "updated_at": "2025-05-09T20:39:21Z",
381      "mode": "test",
382      "form_type": "return_packing_slip",
383      "form_url": "https://easypost-files.s3-us-west-2.amazonaws.com/files/form/20250509/827694e0c57149079d691ac3fb85e2b1.pdf",
384      "submitted_electronically": null
385    }
386  ],
387  "fees": [
388    {
389      "object": "Fee",
390      "type": "PostageFee",
391      "amount": "11.01000",
392      "charged": true,
393      "refunded": false
394    }
395  ],
396  "object": "Shipment"
397}