# Carrier Document Upload

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](#register-a-document). 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](#register-a-document), then call [Send label documents](#send-documents-to-the-carrier) 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](https://help.shipstation.com/hc/en-us/articles/50888603341211). This is useful for operations teams who need to upload documents manually or as a fallback if API integration issues occur.

LIMITED AVAILABILITY
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.

details
summary
FedEx accepted document types
- `usmca_commercial_invoice_certification_of_origin`
- `usmca_certification_of_origin`
- `pro_forma_invoice`
- `other`


details
summary
UPS accepted document types
- `certificate_of_origin`
- `usmca_commercial_invoice_certification_of_origin`
- `usmca_certification_of_origin`
- `other`
- `authorization_form`
- `export_accompanying_document`
- `export_license`
- `import_permit`
- `power_of_attorney`
- `packing_list`
- `sed_document`
- `shippers_letter_of_instruction`
- `declaration`


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.

## Requirements

### Account setup & prerequisites

- For standalone UPS accounts, you must have a valid 6-digit UPS shipper number enabled for **"Upload Forms Created Offline"** to avoid API errors.


### UPS document & upload restrictions

| 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. |


## How it works

Uploading a document is a three-step flow:

1. **Register the document.** 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`.
2. **Upload the file to Amazon S3.** 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.
3. **Send to the carrier.** Once the file is uploaded, call the [send documents](#send-documents-to-the-carrier) 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.

## Endpoints

| 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 |


## Supported document types

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` |  | ✓ |


## Supported file formats

Documents can be uploaded in the following formats. If you omit `format` when registering, `PDF` is used.

- `PDF`
- `PNG`


## Document statuses

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. |


## Full API reference

For complete request and response details for all document upload endpoints, see the [Documents API reference](/apis/openapi/documents).