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

Carrier Connections

Community Edition
Core Feature

Every Karrio project comes with comprehensive carrier connection management, providing seamless integration with 50+ shipping carriers worldwide through a unified API interface, automated credential management, and real-time connection monitoring.

Karrio’s Carrier Connections provide a unified API to integrate with 50+ shipping carriers worldwide. Manage all your carrier accounts, credentials, and configurations in one place while maintaining consistent interfaces across different shipping providers.

Overview

Instead of integrating with dozens of different carrier APIs, each with their own authentication methods, data formats, and business logic, Karrio provides a single, standardized interface. Whether you’re shipping with FedEx, UPS, DHL, or any other supported carrier, the integration process remains consistent.

Key Benefits

  • Universal Integration: One API interface for all supported carriers
  • Standardized Data: Consistent request/response formats across carriers
  • Simplified Authentication: Manage all carrier credentials in one place
  • Real-time Rate Comparison: Compare rates across multiple carriers instantly
  • Test and Production: Separate environments for development and live operations

Architecture

Connection Management Flow

Core Components

1. Connection Registry

Central registry for all carrier connections:

  • Credential Management: Secure storage and encryption of carrier API credentials
  • Connection Status: Real-time monitoring of carrier API availability
  • Configuration Management: Carrier-specific settings and preferences
  • Access Control: User and organization-level access to specific carriers

2. API Abstraction Layer

Standardizes communication with different carrier APIs:

  • Request Translation: Converts unified requests to carrier-specific formats
  • Response Normalization: Standardizes carrier responses to unified format
  • Error Handling: Consistent error handling across all carriers

3. Authentication Manager

Handles diverse carrier authentication methods:

  • OAuth Integration: OAuth2 flows for supported carriers
  • API Key Management: Secure API key storage and rotation
  • Certificate Handling: SSL certificate management for carriers requiring them
  • Token Refresh: Automatic token refresh for time-limited credentials

Getting Started

1. Create Your First Carrier Connection

1curl -X POST "https://api.karrio.io/v1/connections" \
2  -H "Authorization: Token YOUR_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "carrier_name": "fedex",
6    "carrier_id": "fedex_production",
7    "credentials": {
8      "account_number": "YOUR_FEDEX_ACCOUNT",
9      "meter_number": "YOUR_METER_NUMBER",
10      "user_key": "YOUR_USER_KEY",
11      "password": "YOUR_PASSWORD"
12    },
13    "test_mode": false,
14    "active": true
15  }'

2. Test Your Connection

Get carrier services
1curl -X GET "https://api.karrio.io/v1/carriers/fedex/services" \
2  -H "Authorization: Token YOUR_API_KEY"
3
4# Test with a rate request
5curl -X POST "https://api.karrio.io/v1/proxy/rates" \
6  -H "Authorization: Token YOUR_API_KEY" \
7  -H "Content-Type: application/json" \
8  -d '{
9    "shipper": {
10      "postal_code": "10001",
11      "country_code": "US"
12    },
13    "recipient": {
14      "postal_code": "90210",
15      "country_code": "US"
16    },
17    "parcels": [{
18      "weight": 2.5,
19      "weight_unit": "LB"
20    }],
21    "carrier_ids": ["fedex_production"]
22  }'

3. Configure Multiple Carriers

Add UPS connection
1curl -X POST "https://api.karrio.io/v1/connections" \
2  -H "Authorization: Token YOUR_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "carrier_name": "ups",
6    "carrier_id": "ups_production",
7    "credentials": {
8      "account_number": "UPS_ACCOUNT",
9      "access_key": "UPS_ACCESS_KEY",
10      "user_id": "UPS_USER_ID",
11      "password": "UPS_PASSWORD"
12    },
13    "test_mode": false,
14    "active": true
15  }'
16
17# Add USPS connection
18curl -X POST "https://api.karrio.io/v1/connections" \
19  -H "Authorization: Token YOUR_API_KEY" \
20  -H "Content-Type: application/json" \
21  -d '{
22    "carrier_name": "usps",
23    "carrier_id": "usps_production",
24    "credentials": {
25      "username": "USPS_USERNAME",
26      "password": "USPS_PASSWORD"
27    },
28    "test_mode": false,
29    "active": true
30  }'
31
32# Compare rates across all carriers
33curl -X POST "https://api.karrio.io/v1/proxy/rates" \
34  -H "Authorization: Token YOUR_API_KEY" \
35  -H "Content-Type: application/json" \
36  -d '{
37    "shipper": {
38      "postal_code": "10001",
39      "country_code": "US"
40    },
41    "recipient": {
42      "postal_code": "90210",
43      "country_code": "US"
44    },
45    "parcels": [{
46      "weight": 2.5,
47      "weight_unit": "LB"
48    }],
49    "carrier_ids": ["fedex_production", "ups_production", "usps_production"]
50  }'

Use Cases

E-commerce Integration

Integrate shipping into your e-commerce platform:

Create shipment with auto-carrier selection
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_ground",
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    },
15    "recipient": {
16      "person_name": "Jane Smith",
17      "address_line1": "456 Oak Ave",
18      "city": "Los Angeles",
19      "state_code": "CA",
20      "postal_code": "90210",
21      "country_code": "US"
22    },
23    "parcels": [{
24      "weight": 2.5,
25      "weight_unit": "LB",
26      "length": 10,
27      "width": 8,
28      "height": 6,
29      "dimension_unit": "IN"
30    }],
31    "carrier_ids": ["fedex_production"]
32  }'

Multi-Carrier Rate Shopping

Compare rates and select best option:

Get rates from multiple carriers
1curl -X POST "https://api.karrio.io/v1/proxy/rates" \
2  -H "Authorization: Token YOUR_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "shipper": {
6      "postal_code": "10001",
7      "country_code": "US"
8    },
9    "recipient": {
10      "postal_code": "90210",
11      "country_code": "US"
12    },
13    "parcels": [{
14      "weight": 2.5,
15      "weight_unit": "LB"
16    }],
17    "services": ["ground", "express"]
18  }' | jq '.rates | sort_by(.total_charge)'

International Shipping

Handle customs and international requirements:

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": "Jean Dupont",
15      "address_line1": "456 Rue de la Paix",
16      "city": "Paris",
17      "postal_code": "75001",
18      "country_code": "FR"
19    },
20    "parcels": [{
21      "weight": 2.5,
22      "weight_unit": "LB",
23      "items": [{
24        "title": "Electronics",
25        "quantity": 1,
26        "value_amount": 150.00,
27        "value_currency": "USD",
28        "origin_country": "US"
29      }]
30    }],
31    "customs": {
32      "commodities": [{
33        "title": "Electronics",
34        "quantity": 1,
35        "value_amount": 150.00,
36        "value_currency": "USD",
37        "origin_country": "US"
38      }],
39      "content_type": "merchandise",
40      "commercial_invoice": true
41    },
42    "carrier_ids": ["fedex_production"]
43  }'

Advanced Features

Connection Management

List All Connections

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

Update Connection Settings

1curl -X PATCH "https://api.karrio.io/v1/connections/CONNECTION_ID" \
2  -H "Authorization: Token YOUR_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "active": false,
6    "config": {
7      "default_service": "ground"
8    }
9  }'

Remove Connection

1curl -X DELETE "https://api.karrio.io/v1/connections/CONNECTION_ID" \
2  -H "Authorization: Token YOUR_API_KEY"

Carrier-Specific Configuration

Each carrier supports specific configuration options:

FedEx with custom config
1curl -X POST "https://api.karrio.io/v1/connections" \
2  -H "Authorization: Token YOUR_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "carrier_name": "fedex",
6    "carrier_id": "fedex_custom",
7    "credentials": {
8      "account_number": "YOUR_ACCOUNT",
9      "meter_number": "YOUR_METER",
10      "user_key": "YOUR_KEY",
11      "password": "YOUR_PASSWORD"
12    },
13    "config": {
14      "smart_post_hub_id": "5087",
15      "freight_account_number": "FREIGHT_ACCOUNT"
16    },
17    "test_mode": false
18  }'

Security & Compliance

Credential Security

  • Encryption: All credentials encrypted at rest using AES-256
  • Access Control: Role-based access to carrier connections
  • Audit Logging: Complete audit trail of credential access and modifications
  • Automatic Rotation: Support for automatic credential rotation where supported by carriers

Error Handling

Common connection errors and solutions:

Test connection health
1curl -X POST "https://api.karrio.io/v1/proxy/rates" \
2  -H "Authorization: Token YOUR_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "shipper": {"postal_code": "10001", "country_code": "US"},
6    "recipient": {"postal_code": "90210", "country_code": "US"},
7    "parcels": [{"weight": 1, "weight_unit": "LB"}],
8    "carrier_ids": ["CONNECTION_ID"]
9  }'
10
11# Handle common errors:
12# - 401: Invalid credentials
13# - 424: Carrier API unavailable
14# - 400: Invalid request data

Best Practices

Connection Naming

Use descriptive carrier IDs for better organization:

Good examples
1"carrier_id": "fedex_production_main"
2"carrier_id": "ups_test_warehouse_1"
3"carrier_id": "dhl_express_eu"
4
5# Avoid generic names
6"carrier_id": "fedex1"
7"carrier_id": "test"

Environment Management

Separate test and production connections:

Test environment
1{
2  "carrier_id": "fedex_test",
3  "test_mode": true
4}
5
6# Production environment
7{
8  "carrier_id": "fedex_production",
9  "test_mode": false
10}

Metadata Usage

Use metadata for organizational purposes:

1{
2  "carrier_id": "fedex_warehouse_1",
3  "metadata": {
4    "warehouse": "east-coast",
5    "department": "fulfillment",
6    "cost_center": "logistics"
7  }
8}

What’s Next?

Need help connecting a carrier? Join our community Discord or check our carrier-specific guides.