Paperless Trade & Document Upload

Karrio’s paperless trade functionality enables electronic customs documentation for international shipments, supporting both UPS and FedEx carriers. Upload trade documents electronically to reduce paper-based processes and accelerate customs clearance.

Overview

Paperless trade eliminates physical customs documentation by allowing electronic upload of required documents. These documents are transmitted to customs authorities and carriers for faster processing.

Supported Carriers

Supported Document Types

• commercial_invoice - Commercial invoice for customs
• pro_forma_invoice - Pro forma invoice
• certificate_of_origin - Certificate of origin
• packing_list - Detailed packing list
• other - Other customs documents

Document Upload API

Upload Documents

Upload customs documents for a shipment to enable paperless trade processing.

1curl -X POST "https://api.karrio.io/v1/documents/uploads" \
2  -H "Authorization: Token YOUR_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "shipment_id": "shp_1234567890",
6    "document_files": [
7      {
8        "doc_type": "commercial_invoice",
9        "doc_name": "commercial_invoice.pdf",
10        "doc_format": "pdf",
11        "doc_file": "base64_encoded_document_content"
12      },
13      {
14        "doc_type": "certificate_of_origin",
15        "doc_name": "certificate_of_origin.pdf",
16        "doc_format": "pdf",
17        "doc_file": "base64_encoded_document_content"
18      }
19    ],
20    "reference": "CUSTOMS_DOCS_001"
21  }'

Response:

1{
2  "id": "uprec_1234567890",
3  "carrier_name": "fedex",
4  "carrier_id": "fedex_production",
5  "documents": [
6    {
7      "doc_id": "090493e181586308",
8      "file_name": "commercial_invoice.pdf"
9    },
10    {
11      "doc_id": "090493e181586309",
12      "file_name": "certificate_of_origin.pdf"
13    }
14  ],
15  "reference": "CUSTOMS_DOCS_001",
16  "messages": []
17}

Retrieve Upload Records

1curl -X GET "https://api.karrio.io/v1/documents/uploads" \
2  -H "Authorization: Token YOUR_API_KEY"

1curl -X GET "https://api.karrio.io/v1/documents/uploads/uprec_1234567890" \
2  -H "Authorization: Token YOUR_API_KEY"

UPS Implementation

How UPS Paperless Trade Works

UPS paperless trade uses a smart FormType selection based on document availability:

• FormType=“07” - User-created forms (when documents are uploaded)
• FormType=“03” - API-generated commercial invoice (paperless without documents)
• FormType=“01” - Traditional paper forms (when paperless is disabled)

1. Upload Documents (Optional)

For UPS shipments, you can upload documents in advance:

1curl -X POST "https://api.karrio.io/v1/documents/uploads" \
2  -H "Authorization: Token YOUR_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "shipment_id": "shp_ups_example",
6    "document_files": [
7      {
8        "doc_type": "commercial_invoice",
9        "doc_name": "invoice.pdf",
10        "doc_format": "pdf",
11        "doc_file": "base64_encoded_content"
12      }
13    ]
14  }'

2. Create Shipment with Paperless Trade

Option A: With Pre-uploaded Documents

1curl -X POST "https://api.karrio.io/v1/shipments" \
2  -H "Authorization: Token YOUR_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "service": "ups_worldwide_express",
6    "shipper": {
7      "person_name": "John Doe",
8      "address_line1": "123 Main St",
9      "city": "New York",
10      "state_code": "NY",
11      "postal_code": "10001",
12      "country_code": "US"
13    },
14    "recipient": {
15      "person_name": "Jane Smith",
16      "address_line1": "456 Oak Ave",
17      "city": "London",
18      "postal_code": "SW1A 1AA",
19      "country_code": "GB"
20    },
21    "parcels": [{
22      "weight": 2.5,
23      "weight_unit": "LB"
24    }],
25    "options": {
26      "paperless_trade": true,
27      "doc_references": [
28        {
29          "doc_id": "2016-01-18-11.01.07.589501",
30          "doc_type": "commercial_invoice"
31        }
32      ]
33    },
34    "customs": {
35      "content_type": "merchandise",
36      "incoterm": "DDP",
37      "commodities": [{
38        "description": "Sample Product",
39        "quantity": 1,
40        "value_amount": 100.00,
41        "value_currency": "USD",
42        "weight": 2.5,
43        "weight_unit": "LB",
44        "origin_country": "US"
45      }]
46    }
47  }'

Option B: Paperless Without Documents (Uses API-generated invoice)

1curl -X POST "https://api.karrio.io/v1/shipments" \
2  -H "Authorization: Token YOUR_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "service": "ups_worldwide_express",
6    "shipper": { /* same as above */ },
7    "recipient": { /* same as above */ },
8    "parcels": [{ /* same as above */ }],
9    "options": {
10      "paperless_trade": true
11      // No doc_references - UPS will use FormType="03" for API-generated invoice
12    },
13    "customs": { /* same as above */ }
14  }'

FedEx Implementation

How FedEx Electronic Trade Documents Work

FedEx supports two document workflows:

1. Inline Documents - Upload documents during shipment creation
2. Pre-uploaded Documents - Reference previously uploaded documents

Option A: Inline Document Upload

1curl -X POST "https://api.karrio.io/v1/shipments" \
2  -H "Authorization: Token YOUR_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "service": "fedex_international_priority",
6    "shipper": {
7      "person_name": "John Doe",
8      "address_line1": "123 Main St",
9      "city": "New York",
10      "state_code": "NY",
11      "postal_code": "10001",
12      "country_code": "US"
13    },
14    "recipient": {
15      "person_name": "Marie Dubois",
16      "address_line1": "123 Rue de la Paix",
17      "city": "Paris",
18      "postal_code": "75001",
19      "country_code": "FR"
20    },
21    "parcels": [{
22      "weight": 1.5,
23      "weight_unit": "LB"
24    }],
25    "options": {
26      "paperless_trade": true,
27      "doc_files": [
28        {
29          "doc_type": "commercial_invoice",
30          "doc_name": "commercial_invoice.pdf",
31          "doc_format": "pdf",
32          "doc_file": "base64_encoded_document_content"
33        }
34      ]
35    },
36    "customs": {
37      "content_type": "merchandise",
38      "incoterm": "DDP",
39      "commodities": [{
40        "description": "T-Shirt",
41        "quantity": 2,
42        "value_amount": 25.00,
43        "value_currency": "USD",
44        "weight": 0.5,
45        "weight_unit": "LB",
46        "origin_country": "US"
47      }]
48    }
49  }'

Option B: Reference Pre-uploaded Documents

1. Upload documents first (same as UPS example above)
1# 2. Create shipment with document references
2curl -X POST "https://api.karrio.io/v1/shipments" \
3  -H "Authorization: Token YOUR_API_KEY" \
4  -H "Content-Type: application/json" \
5  -d '{
6    "service": "fedex_international_priority",
7    "shipper": { /* same as above */ },
8    "recipient": { /* same as above */ },
9    "parcels": [{ /* same as above */ }],
10    "options": {
11      "paperless_trade": true,
12      "doc_references": [
13        {
14          "doc_id": "090493e181586308",
15          "doc_type": "commercial_invoice"
16        }
17      ]
18    },
19    "customs": { /* same as above */ }
20  }'

Document Workflow

Best Practices

Document Preparation

1. File Format: PDF is recommended for all document types
2. File Size: Keep documents under 5MB per file
3. Encoding: Always base64 encode document content
4. Naming: Use descriptive filenames for tracking

Implementation Tips

1. UPS: Enable paperless_trade: true even without documents for API-generated invoices
2. FedEx: Use inline doc_files for simple workflows, pre-upload for complex scenarios
3. Error Handling: Always check the messages array in responses for warnings
4. Testing: Test with both document and no-document scenarios

Error Handling

Common Issues

Response Validation

Always check the response messages array:

1{
2  "id": "uprec_1234567890",
3  "messages": [
4    {
5      "carrier_name": "fedex",
6      "carrier_id": "fedex_production",
7      "message": "Document uploaded successfully",
8      "code": "SUCCESS"
9    }
10  ]
11}

Need help? Join our community Discord or contact our support team.