📖 Looking for karrio's legacy docs? Visit docs.karrio.io

International Shipments & Customs

Community Edition
International Feature

Karrio’s international shipping capabilities handle the complexities of cross-border commerce, including automatic customs documentation generation, duty calculation, and compliance with international trade regulations.

Overview

International shipping with Karrio includes:

  • Customs Documentation: Automatic generation of commercial invoices, customs forms, and certificates
  • Compliance Management: Ensure compliance with international trade regulations

International Shipping Workflow

API Reference

Basic International Shipment

Create an international shipment with customs declaration:

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      "company_name": "Example Corp",
9      "address_line1": "123 Main St",
10      "city": "New York",
11      "state_code": "NY",
12      "postal_code": "10001",
13      "country_code": "US",
14      "phone_number": "555-1234",
15      "email": "john@example.com"
16    },
17    "recipient": {
18      "person_name": "Marie Dubois",
19      "company_name": "Paris Imports",
20      "address_line1": "123 Rue de la Paix",
21      "city": "Paris",
22      "postal_code": "75001",
23      "country_code": "FR",
24      "phone_number": "+33-1-42-60-30-30",
25      "email": "marie@parisimports.fr"
26    },
27    "parcels": [{
28      "weight": 2.5,
29      "weight_unit": "LB",
30      "length": 10,
31      "width": 8,
32      "height": 6,
33      "dimension_unit": "IN"
34    }],
35    "customs": {
36      "content_type": "merchandise",
37      "content_description": "Clothing items",
38      "incoterm": "DDP",
39      "invoice": "INV-2024-001",
40      "invoice_date": "2024-01-15",
41      "commercial_invoice": true,
42      "commodities": [{
43        "description": "Cotton T-Shirt",
44        "quantity": 2,
45        "value_amount": 25.00,
46        "value_currency": "USD",
47        "weight": 0.5,
48        "weight_unit": "LB",
49        "origin_country": "US",
50        "hs_code": "6109100010"
51      }]
52    }
53  }'

Response:

1{
2  "id": "shp_1234567890",
3  "carrier_name": "fedex",
4  "service": "fedex_international_priority",
5  "tracking_number": "1234567890123456",
6  "status": "purchased",
7  "selected_rate": {
8    "total_charge": 45.99,
9    "currency": "USD",
10    "transit_days": 2
11  },
12  "label_url": "https://api.karrio.io/v1/documents/label_123.pdf",
13  "invoice_url": "https://api.karrio.io/v1/documents/invoice_123.pdf",
14  "customs": {
15    "content_type": "merchandise",
16    "incoterm": "DDP",
17    "commodities": [{
18      "description": "Cotton T-Shirt",
19      "quantity": 2,
20      "value_amount": 25.00,
21      "value_currency": "USD",
22      "hs_code": "6109100010"
23    }]
24  }
25}

International Shipment with Detailed Customs

Include comprehensive customs information:

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      "company_name": "Example Corp",
9      "address_line1": "123 Main St",
10      "city": "New York",
11      "state_code": "NY",
12      "postal_code": "10001",
13      "country_code": "US",
14      "tax_id": "123456789"
15    },
16    "recipient": {
17      "person_name": "Hans Mueller",
18      "company_name": "Berlin Imports GmbH",
19      "address_line1": "Unter den Linden 1",
20      "city": "Berlin",
21      "postal_code": "10117",
22      "country_code": "DE",
23      "tax_id": "DE123456789"
24    },
25    "parcels": [{
26      "weight": 5.0,
27      "weight_unit": "LB"
28    }],
29    "customs": {
30      "content_type": "merchandise",
31      "content_description": "Electronic components",
32      "incoterm": "DDU",
33      "invoice": "INV-2024-002",
34      "invoice_date": "2024-01-15",
35      "commercial_invoice": true,
36      "certify": true,
37      "signer": "John Doe",
38      "commodities": [{
39        "description": "Electronic Circuit Board",
40        "quantity": 1,
41        "value_amount": 150.00,
42        "value_currency": "USD",
43        "weight": 2.0,
44        "weight_unit": "LB",
45        "origin_country": "US",
46        "hs_code": "8534001000",
47        "sku": "ECB-001"
48      }, {
49        "description": "Power Supply Unit",
50        "quantity": 1,
51        "value_amount": 75.00,
52        "value_currency": "USD",
53        "weight": 3.0,
54        "weight_unit": "LB",
55        "origin_country": "US",
56        "hs_code": "8504401000",
57        "sku": "PSU-001"
58      }],
59      "duty": {
60        "paid_by": "recipient",
61        "currency": "USD",
62        "declared_value": 225.00
63      }
64    }
65  }'

Document-Only Shipment

Create a shipment for documents only:

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      "postal_code": "10001",
11      "country_code": "US"
12    },
13    "recipient": {
14      "person_name": "Marie Dubois",
15      "address_line1": "123 Rue de la Paix",
16      "city": "Paris",
17      "postal_code": "75001",
18      "country_code": "FR"
19    },
20    "parcels": [{
21      "weight": 0.5,
22      "weight_unit": "LB",
23      "is_document": true
24    }],
25    "customs": {
26      "content_type": "documents",
27      "content_description": "Business documents",
28      "commodities": [{
29        "description": "Business contracts",
30        "quantity": 1,
31        "value_amount": 0.00,
32        "value_currency": "USD",
33        "weight": 0.5,
34        "weight_unit": "LB"
35      }]
36    }
37  }'

Customs Information

Content Types

Different content types for international shipments:

  • merchandise: Commercial goods for sale
  • documents: Business or personal documents
  • gift: Personal gifts (value restrictions apply)
  • sample: Product samples for evaluation
  • return_merchandise: Returned goods
  • other: Other content types

Incoterms

International Commercial Terms define responsibilities:

  • DDP (Delivered Duty Paid): Seller pays all duties and taxes
  • DDU (Delivered Duty Unpaid): Buyer pays duties and taxes
  • CFR (Cost and Freight): Seller pays freight, buyer pays duties
  • CIF (Cost, Insurance, and Freight): Seller pays freight and insurance
  • EXW (Ex Works): Buyer handles all shipping and duties
  • FCA (Free Carrier): Seller delivers to carrier
  • FOB (Free on Board): Transfer of risk at shipping point

Commodity Information

Required information for each commodity:

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": "dhl_express",
6    "shipper": {...},
7    "recipient": {...},
8    "parcels": [{
9      "weight": 3.0,
10      "weight_unit": "KG"
11    }],
12    "customs": {
13      "content_type": "merchandise",
14      "incoterm": "DDP",
15      "commodities": [{
16        "description": "Wireless Headphones",
17        "quantity": 1,
18        "value_amount": 199.99,
19        "value_currency": "USD",
20        "weight": 0.5,
21        "weight_unit": "KG",
22        "origin_country": "CN",
23        "hs_code": "8518300000",
24        "sku": "WH-001",
25        "manufacturer": "TechCorp",
26        "made_in": "China"
27      }]
28    }
29  }'

Duty and Tax Management

Duty Payment Options

Configure who pays duties and taxes:

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    "recipient": {...},
8    "parcels": [...],
9    "customs": {
10      "content_type": "merchandise",
11      "incoterm": "DDU",
12      "commodities": [...],
13      "duty": {
14        "paid_by": "recipient",
15        "currency": "USD",
16        "declared_value": 500.00,
17        "account_number": "123456789"
18      }
19    }
20  }'

Third-Party Billing

Use third-party billing for duties:

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    "recipient": {...},
8    "billing_address": {
9      "person_name": "Billing Contact",
10      "company_name": "Billing Company",
11      "address_line1": "456 Billing St",
12      "city": "Billing City",
13      "postal_code": "12345",
14      "country_code": "US"
15    },
16    "customs": {
17      "content_type": "merchandise",
18      "incoterm": "DDP",
19      "commodities": [...],
20      "duty": {
21        "paid_by": "third_party",
22        "currency": "USD",
23        "declared_value": 500.00,
24        "account_number": "987654321"
25      },
26      "duty_billing_address": {
27        "person_name": "Duty Payer",
28        "company_name": "Duty Company",
29        "address_line1": "789 Duty St",
30        "city": "Duty City",
31        "postal_code": "54321",
32        "country_code": "US"
33      }
34    }
35  }'

International Options

Special Services

International shipping options:

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    "recipient": {...},
8    "parcels": [...],
9    "options": {
10      "insurance": 500.00,
11      "signature_confirmation": true,
12      "dangerous_good": false,
13      "declared_value": 500.00,
14      "email_notification": true,
15      "email_notification_to": "customer@example.com"
16    },
17    "customs": {
18      "content_type": "merchandise",
19      "incoterm": "DDP",
20      "commodities": [...]
21    }
22  }'

Currency Handling

Handle multiple currencies:

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": "dhl_express",
6    "shipper": {...},
7    "recipient": {...},
8    "parcels": [...],
9    "options": {
10      "currency": "EUR",
11      "declared_value": 420.00
12    },
13    "customs": {
14      "content_type": "merchandise",
15      "incoterm": "DDP",
16      "commodities": [{
17        "description": "Product",
18        "quantity": 1,
19        "value_amount": 420.00,
20        "value_currency": "EUR",
21        "weight": 1.0,
22        "weight_unit": "KG"
23      }]
24    }
25  }'

Multi-Country Scenarios

US to Canada

Common North American shipping:

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": "Jane Smith",
16      "address_line1": "456 Maple Ave",
17      "city": "Toronto",
18      "state_code": "ON",
19      "postal_code": "M5V 3A8",
20      "country_code": "CA"
21    },
22    "parcels": [{
23      "weight": 2.0,
24      "weight_unit": "LB"
25    }],
26    "customs": {
27      "content_type": "merchandise",
28      "incoterm": "DDU",
29      "commodities": [{
30        "description": "Electronics",
31        "quantity": 1,
32        "value_amount": 100.00,
33        "value_currency": "USD",
34        "weight": 2.0,
35        "weight_unit": "LB",
36        "origin_country": "US"
37      }]
38    }
39  }'

US to EU

Shipping to European Union:

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      "postal_code": "10001",
11      "country_code": "US"
12    },
13    "recipient": {
14      "person_name": "Hans Mueller",
15      "address_line1": "Unter den Linden 1",
16      "city": "Berlin",
17      "postal_code": "10117",
18      "country_code": "DE"
19    },
20    "parcels": [{
21      "weight": 3.0,
22      "weight_unit": "KG"
23    }],
24    "customs": {
25      "content_type": "merchandise",
26      "incoterm": "DDP",
27      "commodities": [{
28        "description": "Consumer Electronics",
29        "quantity": 1,
30        "value_amount": 200.00,
31        "value_currency": "USD",
32        "weight": 3.0,
33        "weight_unit": "KG",
34        "origin_country": "US",
35        "hs_code": "8517120000"
36      }]
37    }
38  }'

Asia-Pacific Shipping

Shipping to Asia-Pacific region:

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": "dhl_express",
6    "shipper": {
7      "person_name": "John Doe",
8      "address_line1": "123 Main St",
9      "city": "New York",
10      "postal_code": "10001",
11      "country_code": "US"
12    },
13    "recipient": {
14      "person_name": "Tanaka Hiroshi",
15      "address_line1": "1-1-1 Shibuya",
16      "city": "Tokyo",
17      "postal_code": "150-0002",
18      "country_code": "JP"
19    },
20    "parcels": [{
21      "weight": 1.5,
22      "weight_unit": "KG"
23    }],
24    "customs": {
25      "content_type": "merchandise",
26      "incoterm": "DDU",
27      "commodities": [{
28        "description": "Fashion Accessories",
29        "quantity": 1,
30        "value_amount": 150.00,
31        "value_currency": "USD",
32        "weight": 1.5,
33        "weight_unit": "KG",
34        "origin_country": "US",
35        "hs_code": "4202220000"
36      }]
37    }
38  }'

Error Handling

Customs Validation Errors

Handle customs-related errors:

1{
2  "errors": [
3    {
4      "code": "CUSTOMS_INVALID_HS_CODE",
5      "message": "Invalid HS code for commodity",
6      "details": "HS code 1234567890 is not valid"
7    }
8  ]
9}