Document Upload lets you submit self-prepared customs paperwork — such as Pro Forma Invoices, USMCA forms (for example, the USMCA Certification of Origin), and other supporting documents — directly to the carrier. Use it whenever a shipment requires supplemental international documentation, helping to prevent customs delays and delivery issues.
Documents can be provided at either the shipment level or the label level — that is, before or after a label is generated:
- Shipment level (before a label exists). Register the document with Register a document for a shipment. Documents registered at the shipment level are forwarded to the carrier automatically.
- Label level (after a label is generated). Register the document with Register a document for a label, then call Send label documents to transmit it to the carrier.
To enable document upload for a shipment or label, set the pending_documents flag on the shipment's customs object.
For step-by-step instructions on uploading documents through the ShipStation API dashboard, see the Customs Declarations: Document Upload help article. This is useful for operations teams who need to upload documents manually or as a fallback if API integration issues occur.
Carrier Document Upload is currently supported for UPS and FedEx only. Accepted document types and file size vary by carrier — expand the lists below for the full set.
FedEx accepted document types
usmca_commercial_invoice_certification_of_originusmca_certification_of_originpro_forma_invoiceother
UPS accepted document types
certificate_of_originusmca_commercial_invoice_certification_of_originusmca_certification_of_originotherauthorization_formexport_accompanying_documentexport_licenseimport_permitpower_of_attorneypacking_listsed_documentshippers_letter_of_instructiondeclaration
Once you have uploaded a document and sent it to the carrier, it cannot be deleted or modified. Please ensure all information is accurate before finalizing.
- For standalone UPS accounts, you must have a valid 6-digit UPS shipper number enabled for "Upload Forms Created Offline" to avoid API errors.
| Limit | Description |
|---|---|
| File size | Maximum 10 MB per file. Maximum 50 MB total per request. |
| Quantity | Maximum 13 files per request. Maximum 13 documents total per shipment. |
Uploading a document is a three-step flow:
- Register the document. Call the register endpoint with the document
type,format, andfile_name. The response returns adocument_idand anuploadtarget — a pre-signed Amazon S3urland a set of formfields. - Upload the file to Amazon S3. Send an HTTP
POSTwithmultipart/form-datato the returnedupload.url, including every key/value pair fromupload.fieldsexactly as returned, followed by afilepart containing the document content. - Send to the carrier. Once the file is uploaded, call the send documents endpoint to transmit all of the label's documents to the carrier.
You can register documents against either a shipment or a label. When you register against a label, ShipStation resolves the carrier, tracking number, and transaction details automatically from the label.
| Method | Endpoint | Description |
|---|---|---|
POST | /v2/labels/{label_id}/documents | Register a document against a label and receive S3 upload URL |
GET | /v2/labels/{label_id}/documents | List documents for a label |
DELETE | /v2/labels/{label_id}/documents/{document_id} | Delete a document (only before sending to carrier) |
POST | /v2/labels/{label_id}/documents/send | Transmit all uploaded documents to the carrier |
GET | /v2/documents/{document_id}/download | Download a document file |
POST | /v2/shipments/{shipment_id}/documents | Register a document against a shipment and receive S3 upload URL |
GET | /v2/shipments/{shipment_id}/documents | List documents for a shipment |
DELETE | /v2/shipments/{shipment_id}/documents/{document_id} | Delete a shipment document (only before creating a label) |
GET | /v2/shipments/{shipment_id}/labels | List shipments and their document statuses |
The document types a carrier accepts differ. Use a value from the table below that is supported by the carrier on your label or shipment.
| Document type | FedEx | UPS |
|---|---|---|
certificate_of_origin | ✓ | |
usmca_commercial_invoice_certification_of_origin | ✓ | ✓ |
usmca_certification_of_origin | ✓ | ✓ |
pro_forma_invoice | ✓ | |
other | ✓ | ✓ |
authorization_form | ✓ | |
export_accompanying_document | ✓ | |
export_license | ✓ | |
import_permit | ✓ | |
power_of_attorney | ✓ | |
packing_list | ✓ | |
sed_document | ✓ | |
shippers_letter_of_instruction | ✓ | |
declaration | ✓ |
Documents can be uploaded in the following formats. If you omit format when registering, PDF is used.
PDFPNG
After a document is registered, its status reflects where it is in the upload and send flow:
| Status | Description |
|---|---|
awaiting_upload | The document is registered and waiting for the file to be uploaded to the provided upload target. |
processing | The uploaded file is being processed. |
processing_claimed | The document has been claimed for processing. |
invalid | The document failed validation and cannot be used. |
uploaded | The file was uploaded successfully and is ready to be sent to the carrier. |
queued | The document is queued to be sent to the carrier. |
sent | The document was transmitted to the carrier. |
failed | Sending the document to the carrier failed. |
For complete request and response details for all document upload endpoints, see the Documents API reference.