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.
SS API: You can also suppress a carrier-generated document by setting the suppress_carrier_generated_documents advanced option on the shipment. Currently, only the commercial invoice is supported, and only for UPS.
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.
NOTE: 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
IMPORTANT:
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:
Call the register endpoint with the document type, format, and file_name. The response returns a document_id and an upload target — a pre-signed Amazon S3 url and a set of form fields.
Send an HTTP POST with multipart/form-data to the returned upload.url, including every key/value pair from upload.fields exactly as returned, followed by a file part containing the document content.
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 | /v1/labels/{label_id}/documents | Register a document against a label and receive S3 upload URL |
GET | /v1/labels/{label_id}/documents | List documents for a label |
DELETE | /v1/labels/{label_id}/documents/{document_id} | Delete a document (only before sending to carrier) |
POST | /v1/labels/{label_id}/documents/send | Transmit all uploaded documents to the carrier |
GET | /v1/documents/{document_id}/download | Download a document file |
POST | /v1/shipments/{shipment_id}/documents | Register a document against a shipment and receive S3 upload URL |
GET | /v1/shipments/{shipment_id}/documents | List documents for a shipment |
DELETE | /v1/shipments/{shipment_id}/documents/{document_id} | Delete a shipment document (only before creating a label) |
GET | /v1/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.