> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stateset.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Batch Operations

> Perform bulk inventory operations for efficient management at scale

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

## Request Body

<ParamField body="operation" type="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
</ParamField>

<ParamField body="items" type="array" required>
  Array of items to process (max 1000 per request)

  <Expandable title="properties">
    <ParamField body="sku" type="string" required>
      SKU of the inventory item
    </ParamField>

    <ParamField body="data" type="object" required>
      Operation-specific data (varies by operation type)
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="options" type="object">
  Batch operation options

  <Expandable title="properties">
    <ParamField body="validate_only" type="boolean">
      Validate without executing. Default: false
    </ParamField>

    <ParamField body="continue_on_error" type="boolean">
      Continue processing on errors. Default: false
    </ParamField>

    <ParamField body="notification_email" type="string">
      Email for completion notification
    </ParamField>
  </Expandable>
</ParamField>

## Response

<ResponseField name="batch_id" type="string">
  Unique identifier for this batch operation
</ResponseField>

<ResponseField name="status" type="string">
  Batch status: `processing`, `completed`, `failed`, `partial`
</ResponseField>

<ResponseField name="summary" type="object">
  Operation summary

  <Expandable title="properties">
    <ResponseField name="total_items" type="integer">
      Total items in batch
    </ResponseField>

    <ResponseField name="processed" type="integer">
      Successfully processed items
    </ResponseField>

    <ResponseField name="failed" type="integer">
      Failed items
    </ResponseField>

    <ResponseField name="skipped" type="integer">
      Skipped items
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="results" type="array">
  Individual item results

  <Expandable title="properties">
    <ResponseField name="sku" type="string">
      Item SKU
    </ResponseField>

    <ResponseField name="status" type="string">
      Item status: `success`, `error`, `skipped`
    </ResponseField>

    <ResponseField name="message" type="string">
      Status message or error details
    </ResponseField>

    <ResponseField name="data" type="object">
      Operation result data
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  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
      }
    }'
  ```

  ```javascript Node.js theme={null}
  const batchResult = await stateset.inventory.batch.create({
    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
    }
  });
  ```

  ```python Python theme={null}
  batch_result = stateset.inventory.batch.create(
      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
      }
  )
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "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
        }
      }
    ]
  }
  ```
</ResponseExample>

## Operation Types

### Bulk Update

Update multiple inventory item properties at once.

```javascript theme={null}
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.

```javascript theme={null}
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.

```javascript theme={null}
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.

```javascript theme={null}
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:

```javascript theme={null}
// 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:

```javascript theme={null}
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

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

## Related Endpoints

* [Inventory Planning](/api-reference/inventory/planning) - Plan inventory levels
* [Inventory Analytics](/api-reference/inventory/analytics) - Analyze inventory data
* [Adjust Inventory](/api-reference/inventory/adjust) - Single item adjustments
* [Transfer Inventory](/api-reference/inventory/transfer) - Single item transfers