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_395cb033b8ed4be6bcacead7782cf0d9",
  "created_at": "2024-01-24T00:05:52Z",
  "updated_at": "2024-01-24T00:05:52Z",
  "mode": "test",
  "form_type": "return_packing_slip",
  "form_url": "https://easypost-files.s3-us-west-2.amazonaws.com/files/form/20240124/a4177d0bc14e456cb91e81f48f90fb83.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  "created_at": "2024-01-24T00:05:50Z",
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": "9405500207552011812542",
16  "updated_at": "2024-01-24T00:05:51Z",
17  "batch_id": null,
18  "batch_status": null,
19  "batch_message": null,
20  "customs_info": {
21    "id": "cstinfo_22c094c28a5849c2831e345cfa8a4809",
22    "object": "CustomsInfo",
23    "created_at": "2024-01-24T00:05:50Z",
24    "updated_at": "2024-01-24T00:05:50Z",
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_a1f6f1d173934f37a2ce669bb6657e3c",
38        "object": "CustomsItem",
39        "created_at": "2024-01-24T00:05:50Z",
40        "updated_at": "2024-01-24T00:05:50Z",
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_550ea165ba4c11eeb9e7ac1f6bc53342",
58    "object": "Address",
59    "created_at": "2024-01-24T00:05:50+00:00",
60    "updated_at": "2024-01-24T00:05:50+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_44286ed3097f46d1adbc382c934ce534",
82    "object": "Parcel",
83    "created_at": "2024-01-24T00:05:50Z",
84    "updated_at": "2024-01-24T00:05:50Z",
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_325a0a9ea29843a4918757c6bebb71b3",
95    "created_at": "2024-01-24T00:05:50Z",
96    "updated_at": "2024-01-24T00:05:51Z",
97    "date_advance": 0,
98    "integrated_form": "none",
99    "label_date": "2024-01-24T00:05:50Z",
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/e82c64213af7be49b1b2aba1ea0c4dcd5f.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_bdc3690cc6634a1fafde081f3b26c3d9",
113      "object": "Rate",
114      "created_at": "2024-01-24T00:05:50Z",
115      "updated_at": "2024-01-24T00:05:50Z",
116      "mode": "test",
117      "service": "Priority",
118      "carrier": "USPS",
119      "rate": "7.33",
120      "currency": "USD",
121      "retail_rate": "15.20",
122      "retail_currency": "USD",
123      "list_rate": "10.89",
124      "list_currency": "USD",
125      "billing_type": "easypost",
126      "delivery_days": 2,
127      "delivery_date": null,
128      "delivery_date_guaranteed": false,
129      "est_delivery_days": 2,
130      "shipment_id": "shp_5889c78f5e5547958e62f6993453f0d9",
131      "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
132    },
133    {
134      "id": "rate_501c02949c3e44b0ab50eebde3068c8b",
135      "object": "Rate",
136      "created_at": "2024-01-24T00:05:50Z",
137      "updated_at": "2024-01-24T00:05:50Z",
138      "mode": "test",
139      "service": "GroundAdvantage",
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_5889c78f5e5547958e62f6993453f0d9",
153      "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
154    },
155    {
156      "id": "rate_9649550ada4944a2b3439289a428761e",
157      "object": "Rate",
158      "created_at": "2024-01-24T00:05:50Z",
159      "updated_at": "2024-01-24T00:05:50Z",
160      "mode": "test",
161      "service": "First",
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_5889c78f5e5547958e62f6993453f0d9",
175      "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
176    },
177    {
178      "id": "rate_4379eb9028654c9d93cf5905d8619163",
179      "object": "Rate",
180      "created_at": "2024-01-24T00:05:50Z",
181      "updated_at": "2024-01-24T00:05:50Z",
182      "mode": "test",
183      "service": "ParcelSelect",
184      "carrier": "USPS",
185      "rate": "6.79",
186      "currency": "USD",
187      "retail_rate": "13.15",
188      "retail_currency": "USD",
189      "list_rate": "9.41",
190      "list_currency": "USD",
191      "billing_type": "easypost",
192      "delivery_days": 3,
193      "delivery_date": null,
194      "delivery_date_guaranteed": false,
195      "est_delivery_days": 3,
196      "shipment_id": "shp_5889c78f5e5547958e62f6993453f0d9",
197      "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
198    },
199    {
200      "id": "rate_03369f5e3a844ec2b88588f2d566eef0",
201      "object": "Rate",
202      "created_at": "2024-01-24T00:05:50Z",
203      "updated_at": "2024-01-24T00:05:50Z",
204      "mode": "test",
205      "service": "Express",
206      "carrier": "USPS",
207      "rate": "49.60",
208      "currency": "USD",
209      "retail_rate": "57.40",
210      "retail_currency": "USD",
211      "list_rate": "49.60",
212      "list_currency": "USD",
213      "billing_type": "easypost",
214      "delivery_days": null,
215      "delivery_date": null,
216      "delivery_date_guaranteed": false,
217      "est_delivery_days": null,
218      "shipment_id": "shp_5889c78f5e5547958e62f6993453f0d9",
219      "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
220    }
221  ],
222  "refund_status": null,
223  "scan_form": null,
224  "selected_rate": {
225    "id": "rate_bdc3690cc6634a1fafde081f3b26c3d9",
226    "object": "Rate",
227    "created_at": "2024-01-24T00:05:50Z",
228    "updated_at": "2024-01-24T00:05:50Z",
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_5889c78f5e5547958e62f6993453f0d9",
244    "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
245  },
246  "tracker": {
247    "id": "trk_a6ead3f2a19d4e1abfd3d1ce4db88ad5",
248    "object": "Tracker",
249    "mode": "test",
250    "tracking_code": "9405500207552011812542",
251    "status": "pre_transit",
252    "status_detail": "status_update",
253    "created_at": "2024-01-24T00:05:51Z",
254    "updated_at": "2024-01-24T00:05:51Z",
255    "signed_by": null,
256    "weight": null,
257    "est_delivery_date": "2024-01-24T00:05:51Z",
258    "shipment_id": "shp_5889c78f5e5547958e62f6993453f0d9",
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:05:51Z",
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-24T12:42:51Z",
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/djE6dHJrX2E2ZWFkM2YyYTE5ZDRlMWFiZmQzZDFjZTRkYjg4YWQ1"
318  },
319  "to_address": {
320    "id": "adr_550c2974ba4c11ee96563cecef1b359e",
321    "object": "Address",
322    "created_at": "2024-01-24T00:05:50+00:00",
323    "updated_at": "2024-01-24T00:05:50+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_550ea165ba4c11eeb9e7ac1f6bc53342",
359    "object": "Address",
360    "created_at": "2024-01-24T00:05:50+00:00",
361    "updated_at": "2024-01-24T00:05:50+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_550c2974ba4c11ee96563cecef1b359e",
381    "object": "Address",
382    "created_at": "2024-01-24T00:05:50+00:00",
383    "updated_at": "2024-01-24T00:05:50+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    {
418      "object": "Form",
419      "id": "form_395cb033b8ed4be6bcacead7782cf0d9",
420      "created_at": "2024-01-24T00:05:52Z",
421      "updated_at": "2024-01-24T00:05:52Z",
422      "mode": "test",
423      "form_type": "return_packing_slip",
424      "form_url": "https://easypost-files.s3-us-west-2.amazonaws.com/files/form/20240124/a4177d0bc14e456cb91e81f48f90fb83.pdf",
425      "submitted_electronically": null
426    }
427  ],
428  "fees": [
429    {
430      "object": "Fee",
431      "type": "LabelFee",
432      "amount": "0.00000",
433      "charged": true,
434      "refunded": false
435    },
436    {
437      "object": "Fee",
438      "type": "PostageFee",
439      "amount": "7.33000",
440      "charged": true,
441      "refunded": false
442    }
443  ],
444  "id": "shp_5889c78f5e5547958e62f6993453f0d9",
445  "object": "Shipment"
446}