POST
/
api
/
v1
/
inventory
/
batch
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
    }
  }'

{
  "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
      }
    }
  ]
}
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)
​
options
object
Batch operation options

​
Response

​
batch_id
string
Unique identifier for this batch operation
​
status
string
Batch status: processing, completed, failed, partial
​
summary
object
Operation summary
​
results
array
Individual item results
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
    }
  }'

{
  "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: 'ops@company.com'
  }
});

// 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