Batch Operations

Perform bulk inventory operations for efficient management at scale

Batch operations allow you to update multiple inventory items in a single API call, significantly improving performance for large-scale operations.

Request Body

operation · string · required

Type of batch operation:

• update - Update multiple items
• adjust - Bulk quantity adjustments
• transfer - Multi-item transfers
• cycle_count - Batch cycle counting
• import - Import inventory data

items · array · required

Array of items to process (max 1000 per request)

Show properties

sku · string · required

SKU of the inventory item

data · object · required

Operation-specific data (varies by operation type)

options · object

Batch operation options

Show properties

validate_only · boolean

Validate without executing. Default: false

continue_on_error · boolean

Continue processing on errors. Default: false

notification_email · string

Email for completion notification

Response

batch_id · string

Unique identifier for this batch operation

status · string

Batch status: processing, completed, failed, partial

summary · object

Operation summary

Show properties

total_items · integer

Total items in batch

processed · integer

Successfully processed items

failed · integer

Failed items

skipped · integer

Skipped items

results · array

Individual item results

Show properties

sku · string

Item SKU

status · string

Item status: success, error, skipped

message · string

Status message or error details

data · object

Operation result data

cURL

curl -X POST https://api.stateset.com/api/v1/inventory/batch \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "adjust",
    "items": [
      {
        "sku": "WIDGET-001",
        "data": {
          "adjustment_type": "absolute",
          "quantity": 150,
          "reason": "Cycle count correction"
        }
      },
      {
        "sku": "GADGET-002",
        "data": {
          "adjustment_type": "relative",
          "quantity": -25,
          "reason": "Damaged goods"
        }
      }
    ],
    "options": {
      "continue_on_error": true
    }
  }'

Response

{
  "batch_id": "batch_1a2b3c4d5e",
  "status": "completed",
  "summary": {
    "total_items": 2,
    "processed": 2,
    "failed": 0,
    "skipped": 0
  },
  "results": [
    {
      "sku": "WIDGET-001",
      "status": "success",
      "message": "Inventory adjusted successfully",
      "data": {
        "previous_quantity": 125,
        "new_quantity": 150,
        "adjustment": 25
      }
    },
    {
      "sku": "GADGET-002",
      "status": "success",
      "message": "Inventory adjusted successfully",
      "data": {
        "previous_quantity": 200,
        "new_quantity": 175,
        "adjustment": -25
      }
    }
  ]
}

Operation Types

Bulk Update

Update multiple inventory item properties at once.

const updates = await stateset.inventory.batch.create({
  operation: 'update',
  items: [
    {
      sku: 'WIDGET-001',
      data: {
        reorder_point: 100,
        price: 29.99,
        category: 'Electronics'
      }
    },
    {
      sku: 'WIDGET-002',
      data: {
        reorder_point: 150,
        price: 34.99,
        category: 'Electronics'
      }
    }
  ]
});

Bulk Adjust

Adjust quantities for multiple items simultaneously.

const adjustments = await stateset.inventory.batch.create({
  operation: 'adjust',
  items: cycleCountResults.map(result => ({
    sku: result.sku,
    data: {
      adjustment_type: 'absolute',
      quantity: result.counted_quantity,
      reason: 'Monthly cycle count',
      reference: `CC-${Date.now()}`
    }
  }))
});

Bulk Transfer

Transfer multiple items between locations.

const transfers = await stateset.inventory.batch.create({
  operation: 'transfer',
  items: [
    {
      sku: 'WIDGET-001',
      data: {
        from_location: 'warehouse_001',
        to_location: 'warehouse_002',
        quantity: 50
      }
    },
    {
      sku: 'GADGET-002',
      data: {
        from_location: 'warehouse_001',
        to_location: 'warehouse_002',
        quantity: 100
      }
    }
  ]
});

Import Inventory

Import inventory data from external systems.

const importResult = await stateset.inventory.batch.create({
  operation: 'import',
  items: csvData.map(row => ({
    sku: row.sku,
    data: {
      name: row.product_name,
      description: row.description,
      quantity: parseInt(row.quantity),
      price: parseFloat(row.price),
      cost: parseFloat(row.cost),
      location_id: row.warehouse,
      category: row.category,
      reorder_point: parseInt(row.reorder_point)
    }
  })),
  options: {
    validate_only: true // Test import first
  }
});

Async Operations

For large batches, operations are processed asynchronously:

// Start batch operation
const batch = await stateset.inventory.batch.create({
  operation: 'update',
  items: largeItemArray, // 10,000+ items
  options: {
    notification_email: '[e-mail]'
  }
});

// Check status
const status = await stateset.inventory.batch.get(batch.batch_id);

// Poll for completion
const checkStatus = async () => {
  const current = await stateset.inventory.batch.get(batch.batch_id);
  
  if (current.status === 'completed') {
    console.log('Batch completed:', current.summary);
  } else if (current.status === 'failed') {
    console.error('Batch failed:', current.error);
  } else {
    // Still processing
    setTimeout(checkStatus, 5000); // Check again in 5 seconds
  }
};

Error Handling

Handle batch operation errors gracefully:

try {
  const batch = await stateset.inventory.batch.create({
    operation: 'adjust',
    items: adjustmentItems,
    options: {
      continue_on_error: false // Stop on first error
    }
  });
  
  // Check for partial failures
  const failedItems = batch.results.filter(r => r.status === 'error');
  
  if (failedItems.length > 0) {
    console.log('Failed items:', failedItems);
    
    // Retry failed items
    const retryBatch = await stateset.inventory.batch.create({
      operation: 'adjust',
      items: failedItems.map(item => ({
        sku: item.sku,
        data: adjustmentItems.find(a => a.sku === item.sku).data
      }))
    });
  }
} catch (error) {
  console.error('Batch operation failed:', error);
}

Performance Tips

• Batch operations can process up to 1,000 items per request
• For larger datasets, use async operations
• Group similar operations together
• Use validate_only to test before executing
• Monitor rate limits for optimal throughput

Related Endpoints

• Inventory Planning - Plan inventory levels
• Inventory Analytics - Analyze inventory data
• Adjust Inventory - Single item adjustments
• Transfer Inventory - Single item transfers