Upload Shipment Documents

The Upload Electronic Trade Document 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.

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

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

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 API under customsDocuments object.

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

Step 1: Create UPS international shipment

• Create the UPS international shipment using the Create Shipment API
• 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