# Upload Shipment Documents

The [Upload Electronic Trade Document](/openapi/shipping/electronic-trade-document/uploadetd) API is an international shipping document upload solution that enables you to electronically upload customs and trade documentation required for international shipments.
This API allows you to submit one or more shipment documents electronically, reducing the need to print, attach, or manually manage physical paperwork.

**Considerations**

- The Upload Electronic Trade Document API supports electronic upload of international shipping documents
- Multiple documents can be uploaded in a single API request
- `carrierAccountId` is required for all carriers ( as of now only DHL and UPS carriers are supported)
- `parcelTrackingNumber` is required only for UPS carrier accounts
- DHL requires documents to be uploaded before shipment creation
- DHL Express supports ETDs with the special service `PAPERLESS`.
- UPS requires documents to be uploaded after shipment creation
- UPS associates shipment documents after shipment creation, using the `parcelTrackingNumber`.
- In certain scenarios, original copies of specific international documents may still be required to be attached to the package.


## How the Document Upload Workflow works

The document upload workflow depends on the carrier associated with the shipment. Currently DHL Express and UPS carriers supported document upload.

### DHL Express Workflow (Upload ETD → Create International Shipment → Attach in customsDocuments)

For DHL international shipments:

- Upload documents before creating the shipment
- Create the DHL international shipment
- Reference the uploaded documents using the s3FileId in the `customs.customsDocuments` object in the shipment request
- Ensure the special service used is `PAPERLESS`


#### How the Workflow Operates

**Step 1: Submit Electronic Trade Document Metadata**

Initiate the process by making a POST request to the ETD Upload API with the document metadata (e.g., file name, document type, and content type).
In response, the system returns:

- A pre-signed S3 upload URL (url)
- A fileName
- A relative `s3FileId` used to reference the uploaded document later


**Step 2: Upload the Document File**

After receiving the response, you must perform a separate HTTP PUT request to the provided url.

- This request must upload the binary content of the file (e.g., PDF or image)
- Upload the same file whose metadata was submitted in step-1


**Step 3: Reference the Document in Shipment Creation**

Once the ETD uploaded successfully, the document is stored in the S3 bucket.

- Once uploaded, the document is stored in the S3 bucket and can later be referenced via the `s3FileId` in [Create International Shipment](/openapi/shipping/shipment/createshipmentv2) API under `customsDocuments` object.


### UPS Workflow (Create International Shipment  → Upload ETDs using parcelTrackingNumber)

For UPS international shipments:

- Create the shipment before uploading documents
- Retrieve the `parcelTrackingNumber` from the shipment response
- Upload documents using the Upload Shipment Documents API
- parcelTrackingNumber is mandatory for UPS document upload
- The system validates the tracking number and associates the documents with the existing shipment


#### How the Workflow Operates

**Step 1: Create UPS international shipment**

- Create the UPS international shipment using the [Create Shipment API](/openapi/shipping/shipment/createshipmentv2)
- Retrieve the `parcelTrackingNumber` from the shipment response


**Step 2: Submit Shipment Document Metadata**

Initiate the process by making a POST request to the ETD Upload API. Include the document metadata (file name, file format, document type, and content type) in the `shipmentDocuments` array, along with the `carrierID` and `parcelTrackingNumber`.

In response, the system returns `shipmentDocuments` array containing these fields:

- A pre-signed S3 upload URL (url)
- A fileName
- Format of the file
- A relative `s3FileId` used to reference the uploaded document later


**Step 3: Upload the Document File**

After receiving the response, you must perform a separate HTTP PUT request to the provided S3 url(s).

- This request must upload the binary content of the file (e.g., PDF or image)
- Upload the same file(s) whose metadata was submitted in step-2