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

Label Generation & Purchase

Community Edition
Label Purchase

Karrio’s label generation system allows you to create and purchase shipping labels from multiple carriers with a single API call. Generate labels in various formats (PDF, PNG, ZPL, EPL) with automatic carrier compliance and tracking number generation.

Overview

The label generation system provides:

  • Multi-Carrier Support: Generate labels for FedEx, UPS, DHL, and other carriers
  • Multiple Formats: Support for PDF, PNG, and ZPL label formats
  • Automatic Compliance: Carrier-specific label requirements handled automatically
  • Document Generation: Commercial invoices and customs forms included

Label Generation Workflow

API Reference

Create Shipment with Label

Create a shipment and generate a label in one request:

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      "phone_number": "555-1234"
15    },
16    "recipient": {
17      "person_name": "Jane Smith",
18      "address_line1": "456 Oak Ave",
19      "city": "Los Angeles",
20      "state_code": "CA",
21      "postal_code": "90210",
22      "country_code": "US",
23      "phone_number": "555-5678"
24    },
25    "parcels": [{
26      "weight": 2.5,
27      "weight_unit": "LB",
28      "length": 10,
29      "width": 8,
30      "height": 6,
31      "dimension_unit": "IN"
32    }],
33    "label_type": "PDF",
34    "options": {
35      "insurance": 100.00,
36      "signature_confirmation": true
37    }
38  }'

Response:

1{
2  "id": "shp_1234567890",
3  "carrier_name": "fedex",
4  "carrier_id": "fedex_production",
5  "service": "fedex_ground",
6  "tracking_number": "1234567890123456",
7  "shipment_identifier": "FDX_SHIP_123",
8  "status": "purchased",
9  "selected_rate": {
10    "id": "rate_1",
11    "carrier_name": "fedex",
12    "service": "fedex_ground",
13    "total_charge": 15.99,
14    "currency": "USD",
15    "transit_days": 3
16  },
17  "label_type": "PDF",
18  "label_url": "https://api.karrio.io/v1/documents/label_123.pdf",
19  "invoice_url": "https://api.karrio.io/v1/documents/invoice_123.pdf",
20  "created_at": "2024-01-15T10:30:00Z"
21}

Rate Shopping with Label Purchase

Create a shipment without service selection to get rates first:

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    "shipper": {
6      "person_name": "John Doe",
7      "address_line1": "123 Main St",
8      "city": "New York",
9      "state_code": "NY",
10      "postal_code": "10001",
11      "country_code": "US"
12    },
13    "recipient": {
14      "person_name": "Jane Smith",
15      "address_line1": "456 Oak Ave",
16      "city": "Los Angeles",
17      "state_code": "CA",
18      "postal_code": "90210",
19      "country_code": "US"
20    },
21    "parcels": [{
22      "weight": 2.5,
23      "weight_unit": "LB"
24    }]
25  }'

Response with Available Rates:

1{
2  "id": "shp_1234567890",
3  "status": "draft",
4  "rates": [
5    {
6      "id": "rate_1",
7      "carrier_name": "fedex",
8      "service": "fedex_ground",
9      "total_charge": 15.99,
10      "currency": "USD",
11      "transit_days": 3
12    },
13    {
14      "id": "rate_2",
15      "carrier_name": "ups",
16      "service": "ups_ground",
17      "total_charge": 16.49,
18      "currency": "USD",
19      "transit_days": 3
20    }
21  ],
22  "label_url": null,
23  "invoice_url": null
24}

Purchase Label for Existing Shipment

Purchase a label for a shipment by selecting a rate:

1curl -X POST "https://api.karrio.io/v1/shipments/shp_1234567890/purchase" \
2  -H "Authorization: Token YOUR_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "selected_rate_id": "rate_1",
6    "label_type": "PDF",
7    "payment": {
8      "paid_by": "sender",
9      "currency": "USD"
10    }
11  }'

Response:

1{
2  "id": "shp_1234567890",
3  "status": "purchased",
4  "tracking_number": "1234567890123456",
5  "selected_rate": {
6    "id": "rate_1",
7    "carrier_name": "fedex",
8    "service": "fedex_ground",
9    "total_charge": 15.99,
10    "currency": "USD"
11  },
12  "label_type": "PDF",
13  "label_url": "https://api.karrio.io/v1/documents/label_123.pdf",
14  "invoice_url": "https://api.karrio.io/v1/documents/invoice_123.pdf"
15}

Label Formats

PDF Labels

Standard PDF format suitable for most printers:

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    "label_type": "PDF",
7    "shipper": {...},
8    "recipient": {...},
9    "parcels": [...]
10  }'

ZPL Labels

ZPL format for Zebra thermal printers:

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_ground",
6    "label_type": "ZPL",
7    "shipper": {...},
8    "recipient": {...},
9    "parcels": [...]
10  }'

PNG Labels

PNG image format for web display:

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    "label_type": "PNG",
7    "shipper": {...},
8    "recipient": {...},
9    "parcels": [...]
10  }'

Label Customization

Label Size Options

Different carriers support various label sizes:

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    "label_type": "PDF",
7    "options": {
8      "label_size": "4x6",
9      "label_format": "PDF_4x6"
10    },
11    "shipper": {...},
12    "recipient": {...},
13    "parcels": [...]
14  }'

Carrier-Specific Features

UPS Label Generation

UPS-specific label features:

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_ground",
6    "label_type": "PDF",
7    "shipper": {
8      "person_name": "John Doe",
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    }],
27    "options": {
28      "saturday_delivery": true,
29      "delivery_confirmation": "signature_required"
30    }
31  }'

FedEx Label Generation

FedEx-specific label features:

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    "label_type": "PDF",
7    "shipper": {
8      "person_name": "John Doe",
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    }],
27    "options": {
28      "saturday_delivery": true,
29      "hold_at_location": true
30    }
31  }'

Error Handling

Label Generation Errors

Handle common label generation errors:

1{
2  "errors": [
3    {
4      "code": "INVALID_ADDRESS",
5      "message": "Invalid recipient address",
6      "details": "Address validation failed for postal code"
7    }
8  ]
9}

Carrier-Specific Errors

Handle carrier-specific validation errors:

1{
2  "errors": [
3    {
4      "code": "CARRIER_ERROR",
5      "message": "FedEx service unavailable",
6      "carrier_name": "fedex",
7      "details": "Service temporarily unavailable in destination area"
8    }
9  ]
10}

Troubleshooting

Common Issues

  1. Address Validation Failures: Ensure complete and accurate address information
  2. Service Unavailability: Check carrier service coverage for destination
  3. Authentication Errors: Validate API keys and carrier credentials

Debugging Tips

  1. Test Mode: Use test mode for development and testing
  2. Verbose Logging: Enable detailed logging for troubleshooting
  3. Error Messages: Check error messages for specific guidance
  4. Carrier Documentation: Refer to carrier-specific documentation

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