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

High Volume
Insiders
PREVIEW

Batch Processing

Every Karrio project comes with comprehensive batch processing capabilities, providing high-performance bulk operations for shipments, orders, tracking requests, and document generation with automatic error handling and progress monitoring.

Features

High-Volume Operations

You don’t have to process shipments one by one. Our batch processing system handles thousands of operations simultaneously with optimized performance and resource utilization.

Batch Processing Dashboard

Screenshot: Batch operation progress monitoring and results interface

Intelligent Error Handling

Individual operation failures don’t affect the entire batch. Failed operations are automatically retried with exponential backoff and detailed error reporting.

Real-Time Progress Monitoring

Track batch operation progress in real-time with detailed status updates, completion rates, and performance metrics.

Asynchronous Processing

Submit large batches and receive webhook notifications when processing completes, allowing your application to handle other tasks.

Operation Optimization

Automatically optimize batch operations by grouping similar requests and leveraging carrier bulk APIs for maximum efficiency.

Additional features

  • Karrio extends batch processing with intelligent batching algorithms and carrier-specific optimizations.
  • Every batch operation includes detailed logging and audit trails for compliance and debugging.
  • Karrio manages resource allocation and rate limiting to prevent API overload.
  • Support for custom batch validation rules and pre-processing workflows.

Data Flow

Batch Processing Flow

API Reference

REST API

Create Batch Shipments

1curl -X POST "https://api.karrio.io/v1/batches/shipments" \
2  -H "Authorization: Token YOUR_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "shipments": [
6      {
7        "recipient": {
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        "parcels": [
16          {
17            "weight": 2.5,
18            "weight_unit": "LB"
19          }
20        ],
21        "service": "ups_ground",
22        "reference": "ORDER-001"
23      },
24      {
25        "recipient": {
26          "person_name": "Jane Smith",
27          "address_line1": "456 Oak Ave",
28          "city": "Los Angeles",
29          "state_code": "CA",
30          "postal_code": "90210",
31          "country_code": "US"
32        },
33        "parcels": [
34          {
35            "weight": 1.8,
36            "weight_unit": "LB"
37          }
38        ],
39        "service": "fedex_ground",
40        "reference": "ORDER-002"
41      }
42    ],
43    "options": {
44      "async": true,
45      "auto_purchase": true,
46      "notify_webhook": "https://your-app.com/webhooks/batch"
47    }
48  }'

Response:

1{
2  "id": "batch_1234567890",
3  "type": "shipments",
4  "status": "processing",
5  "total_count": 2,
6  "completed_count": 0,
7  "success_count": 0,
8  "failed_count": 0,
9  "progress_percentage": 0,
10  "created_at": "2024-01-15T10:30:00Z",
11  "estimated_completion": "2024-01-15T10:32:00Z",
12  "options": {
13    "async": true,
14    "auto_purchase": true,
15    "notify_webhook": "https://your-app.com/webhooks/batch"
16  }
17}

Get Batch Status

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

Response:

1{
2  "id": "batch_1234567890",
3  "type": "shipments",
4  "status": "completed",
5  "total_count": 2,
6  "completed_count": 2,
7  "success_count": 2,
8  "failed_count": 0,
9  "progress_percentage": 100,
10  "created_at": "2024-01-15T10:30:00Z",
11  "completed_at": "2024-01-15T10:31:45Z",
12  "processing_time": 105,
13  "results": [
14    {
15      "index": 0,
16      "success": true,
17      "reference": "ORDER-001",
18      "data": {
19        "id": "shp_1234567890",
20        "tracking_number": "1Z999AA1234567890",
21        "carrier_name": "ups",
22        "label_url": "https://api.karrio.io/v1/shipments/shp_1234567890/label.pdf"
23      }
24    },
25    {
26      "index": 1,
27      "success": true,
28      "reference": "ORDER-002",
29      "data": {
30        "id": "shp_1234567891",
31        "tracking_number": "7721234567",
32        "carrier_name": "fedex",
33        "label_url": "https://api.karrio.io/v1/shipments/shp_1234567891/label.pdf"
34      }
35    }
36  ]
37}

Create Batch Trackers

1curl -X POST "https://api.karrio.io/v1/batches/trackers" \
2  -H "Authorization: Token YOUR_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "trackers": [
6      {
7        "tracking_number": "1Z999AA1234567890",
8        "carrier_name": "ups"
9      },
10      {
11        "tracking_number": "7721234567",
12        "carrier_name": "fedex"
13      }
14    ]
15  }'

Response:

1{
2  "id": "batch_1234567892",
3  "type": "trackers",
4  "status": "completed",
5  "total_count": 2,
6  "success_count": 2,
7  "failed_count": 0,
8  "results": [
9    {
10      "index": 0,
11      "success": true,
12      "data": {
13        "id": "trk_1234567890",
14        "tracking_number": "1Z999AA1234567890",
15        "carrier_name": "ups",
16        "status": "in_transit",
17        "estimated_delivery": "2024-01-18T17:00:00Z"
18      }
19    },
20    {
21      "index": 1,
22      "success": true,
23      "data": {
24        "id": "trk_1234567891",
25        "tracking_number": "7721234567",
26        "carrier_name": "fedex",
27        "status": "delivered",
28        "delivered_at": "2024-01-17T14:30:00Z"
29      }
30    }
31  ]
32}

Use Cases

E-commerce Fulfillment

Perfect for high-volume order processing:

  • Daily Order Processing: Process hundreds of orders in minutes
  • Peak Season Handling: Handle holiday and sale volume spikes
  • Multi-Warehouse Operations: Distribute orders across warehouses efficiently
  • Automated Fulfillment: End-to-end order-to-shipment automation

Enterprise Shipping

Designed for large-scale operations:

  • ERP Integration: Bulk import and process shipments from ERP systems
  • Scheduled Processing: Automated daily/weekly batch operations
  • Resource Optimization: Maximize carrier bulk discounts
  • Compliance Reporting: Generate bulk shipping reports for compliance

3PL Operations

Built for third-party logistics providers:

  • Multi-Client Processing: Process shipments for multiple clients
  • SLA Management: Ensure processing time commitments
  • Cost Optimization: Bulk carrier negotiations and rate optimization
  • Performance Analytics: Track processing efficiency and client satisfaction

Integration Examples

Automated Daily Processing

1class DailyBatchProcessor {
2  constructor(config) {
3    this.warehouseConfig = config.warehouses;
4    this.batchSize = config.batchSize || 100;
5  }
6
7  async runDailyProcessing() {
8    try {
9      console.log("Starting daily batch processing...");
10
11      // 1. Get pending orders
12      const pendingOrders = await this.getPendingOrders();
13      console.log(`Found ${pendingOrders.length} pending orders`);
14
15      // 2. Group orders by warehouse
16      const ordersByWarehouse = this.groupOrdersByWarehouse(pendingOrders);
17
18      // 3. Process each warehouse batch
19      const batchPromises = Object.entries(ordersByWarehouse).map(
20        ([warehouseId, orders]) =>
21          this.processWarehouseBatch(warehouseId, orders),
22      );
23
24      const results = await Promise.all(batchPromises);
25
26      // 4. Generate summary report
27      await this.generateProcessingReport(results);
28
29      console.log("Daily batch processing completed");
30    } catch (error) {
31      console.error("Daily batch processing failed:", error);
32      await this.notifyAdministrators(error);
33    }
34  }
35
36  async processWarehouseBatch(warehouseId, orders) {
37    // Split into smaller batches
38    const batches = this.chunkArray(orders, this.batchSize);
39    const batchResults = [];
40
41    for (const batch of batches) {
42      try {
43        const shipmentRequests = batch.map((order) => ({
44          recipient: order.shipping_address,
45          parcels: this.mapOrderToParcels(order),
46          service: this.selectShippingService(order),
47          reference: order.order_number,
48          metadata: {
49            order_id: order.id,
50            warehouse_id: warehouseId,
51          },
52        }));
53
54        const batchResult = await karrio.batches.createShipments({
55          batchShipmentData: {
56            shipments: shipmentRequests,
57          },
58        });
59
60        batchResults.push(batchResult);
61
62        // Update order statuses
63        await this.updateOrderStatuses(batch, batchResult);
64      } catch (error) {
65        console.error(
66          `Batch processing failed for warehouse ${warehouseId}:`,
67          error,
68        );
69        batchResults.push({ error, orders: batch });
70      }
71    }
72
73    return { warehouseId, results: batchResults };
74  }
75
76  chunkArray(array, size) {
77    const chunks = [];
78    for (let i = 0; i < array.length; i += size) {
79      chunks.push(array.slice(i, i + size));
80    }
81    return chunks;
82  }
83}
84
85// Schedule daily processing
86const processor = new DailyBatchProcessor({
87  warehouses: warehouseConfig,
88  batchSize: 50,
89});
90
91// Using cron or similar scheduler
92cron.schedule("0 9 * * *", () => {
93  processor.runDailyProcessing();
94});

Batch Progress Monitoring

1class BatchMonitor {
2  constructor(batchId) {
3    this.batchId = batchId;
4    this.progressCallbacks = [];
5  }
6
7  onProgress(callback) {
8    this.progressCallbacks.push(callback);
9  }
10
11  async startMonitoring() {
12    const checkProgress = async () => {
13      try {
14        const status = await karrio.batches.retrieve({ id: this.batchId });
15
16        // Notify all callbacks
17        this.progressCallbacks.forEach((callback) => {
18          callback(status);
19        });
20
21        if (status.status === "processing") {
22          setTimeout(checkProgress, 5000); // Check every 5 seconds
23        }
24      } catch (error) {
25        console.error("Failed to check batch progress:", error);
26      }
27    };
28
29    await checkProgress();
30  }
31}
32
33// Usage
34const monitor = new BatchMonitor("batch_1234567890");
35monitor.onProgress((status) => {
36  console.log(`Progress: ${status.progress_percentage}%`);
37  console.log(`Completed: ${status.completed_count}/${status.total_count}`);
38});
39
40await monitor.startMonitoring();

Performance Optimization

Batch Size Optimization

Choose optimal batch sizes based on your use case:

  • Small Batches (10-25): Better error isolation, faster individual results
  • Medium Batches (50-100): Balanced performance and error handling
  • Large Batches (200+): Maximum throughput for stable operations

Error Recovery Strategy

1class BatchErrorRecovery {
2  constructor() {
3    this.maxRetries = 3;
4  }
5
6  async processBatchWithRecovery(operations) {
7    let attempt = 1;
8    let remainingOperations = [...operations];
9
10    while (remainingOperations.length > 0 && attempt <= this.maxRetries) {
11      console.log(
12        `Batch attempt ${attempt}, processing ${remainingOperations.length} operations`,
13      );
14
15      const batch = await karrio.batches.createShipments({
16        batchShipmentData: {
17          shipments: remainingOperations,
18        },
19      });
20
21      // Separate successful and failed operations
22      const failed = batch.results
23        .filter((result) => !result.success)
24        .map((result) => remainingOperations[result.index]);
25
26      const successful = batch.results
27        .filter((result) => result.success)
28        .map((result) => result.data);
29
30      // Process successful operations
31      await this.processSuccessfulShipments(successful);
32
33      // Prepare failed operations for retry
34      remainingOperations = failed.filter((operation) =>
35        this.isRetryable(operation.error),
36      );
37
38      if (remainingOperations.length > 0) {
39        // Apply backoff delay
40        const delay = Math.pow(2, attempt) * 1000;
41        await this.sleep(delay);
42      }
43
44      attempt++;
45    }
46
47    // Handle permanently failed operations
48    if (remainingOperations.length > 0) {
49      await this.handlePermanentFailures(remainingOperations);
50    }
51  }
52
53  isRetryable(error) {
54    const retryableCodes = [
55      "RATE_LIMIT_EXCEEDED",
56      "CARRIER_TIMEOUT",
57      "TEMPORARY_ERROR",
58    ];
59
60    return retryableCodes.includes(error.code);
61  }
62
63  sleep(ms) {
64    return new Promise((resolve) => setTimeout(resolve, ms));
65  }
66}

Getting Started

Ready to implement high-performance batch processing with Karrio? Follow these steps:

  1. Identify batch operations in your shipping workflow
  2. Implement batch request logic using our API examples
  3. Set up progress monitoring and error handling
  4. Optimize batch sizes for your specific use case

Next Steps

  • Learn about workflows for automated batch triggering
  • Explore webhooks for batch completion notifications
  • Set up shipments to understand individual operations
  • Configure admin console for batch monitoring