> ## 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.

# Inventory Planning

> Generate intelligent inventory planning recommendations based on demand forecasting and optimization algorithms

<Note>
  The Inventory Planning API uses machine learning to forecast demand and optimize stock levels across your inventory.
</Note>

## Request Body

<ParamField body="planning_type" type="string" required>
  Type of planning to generate. Options:

  * `demand_forecast` - Predict future demand
  * `reorder_optimization` - Calculate optimal reorder points
  * `seasonal_planning` - Plan for seasonal variations
  * `abc_analysis` - Categorize inventory by value/velocity
</ParamField>

<ParamField body="sku" type="string">
  Specific SKU to plan for. If omitted, plans all inventory items.
</ParamField>

<ParamField body="location_id" type="string">
  Location ID for location-specific planning
</ParamField>

<ParamField body="time_horizon" type="object">
  Planning time horizon

  <Expandable title="properties">
    <ParamField body="value" type="integer" required>
      Number of time units
    </ParamField>

    <ParamField body="unit" type="string" required>
      Time unit: `days`, `weeks`, `months`, `quarters`
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="parameters" type="object">
  Planning-specific parameters

  <Expandable title="properties">
    <ParamField body="service_level" type="number">
      Target service level (0-1). Default: 0.95
    </ParamField>

    <ParamField body="lead_time_days" type="integer">
      Supplier lead time in days
    </ParamField>

    <ParamField body="holding_cost_rate" type="number">
      Annual holding cost as percentage of item value
    </ParamField>

    <ParamField body="ordering_cost" type="number">
      Fixed cost per order
    </ParamField>

    <ParamField body="include_seasonality" type="boolean">
      Include seasonal patterns in forecast. Default: true
    </ParamField>
  </Expandable>
</ParamField>

## Response

<ResponseField name="planning_id" type="string">
  Unique identifier for this planning run
</ResponseField>

<ResponseField name="planning_type" type="string">
  Type of planning performed
</ResponseField>

<ResponseField name="generated_at" type="string">
  ISO 8601 timestamp of when the plan was generated
</ResponseField>

<ResponseField name="items" type="array">
  Array of planning results per inventory item

  <Expandable title="properties">
    <ResponseField name="sku" type="string">
      SKU of the inventory item
    </ResponseField>

    <ResponseField name="item_name" type="string">
      Name of the inventory item
    </ResponseField>

    <ResponseField name="current_stock" type="integer">
      Current available stock level
    </ResponseField>

    <ResponseField name="forecast" type="object">
      Demand forecast details

      <Expandable title="properties">
        <ResponseField name="predicted_demand" type="number">
          Predicted demand for the time horizon
        </ResponseField>

        <ResponseField name="confidence_interval" type="object">
          95% confidence interval

          <Expandable title="properties">
            <ResponseField name="lower" type="number">
              Lower bound of prediction
            </ResponseField>

            <ResponseField name="upper" type="number">
              Upper bound of prediction
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="trend" type="string">
          Demand trend: `increasing`, `decreasing`, `stable`
        </ResponseField>

        <ResponseField name="seasonality_factor" type="number">
          Current seasonal adjustment factor
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="recommendations" type="object">
      Planning recommendations

      <Expandable title="properties">
        <ResponseField name="reorder_point" type="integer">
          Recommended reorder point
        </ResponseField>

        <ResponseField name="safety_stock" type="integer">
          Recommended safety stock level
        </ResponseField>

        <ResponseField name="economic_order_quantity" type="integer">
          Optimal order quantity (EOQ)
        </ResponseField>

        <ResponseField name="max_stock_level" type="integer">
          Maximum recommended stock level
        </ResponseField>

        <ResponseField name="next_order_date" type="string">
          Recommended date for next order
        </ResponseField>

        <ResponseField name="next_order_quantity" type="integer">
          Recommended quantity for next order
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="metrics" type="object">
      Performance metrics

      <Expandable title="properties">
        <ResponseField name="turnover_rate" type="number">
          Annual inventory turnover rate
        </ResponseField>

        <ResponseField name="stockout_risk" type="number">
          Probability of stockout (0-1)
        </ResponseField>

        <ResponseField name="carrying_cost" type="number">
          Estimated annual carrying cost
        </ResponseField>

        <ResponseField name="abc_category" type="string">
          ABC classification: `A`, `B`, or `C`
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="summary" type="object">
  Overall planning summary

  <Expandable title="properties">
    <ResponseField name="total_items" type="integer">
      Number of items planned
    </ResponseField>

    <ResponseField name="total_value" type="number">
      Total inventory value
    </ResponseField>

    <ResponseField name="items_below_reorder" type="integer">
      Items currently below reorder point
    </ResponseField>

    <ResponseField name="urgent_orders" type="array">
      List of SKUs requiring immediate reorder
    </ResponseField>

    <ResponseField name="optimization_savings" type="number">
      Estimated annual savings from optimization
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.stateset.com/api/v1/inventory/planning \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "planning_type": "demand_forecast",
      "time_horizon": {
        "value": 3,
        "unit": "months"
      },
      "parameters": {
        "service_level": 0.95,
        "include_seasonality": true
      }
    }'
  ```

  ```javascript Node.js theme={null}
  const planning = await stateset.inventory.planning.create({
    planning_type: 'demand_forecast',
    time_horizon: {
      value: 3,
      unit: 'months'
    },
    parameters: {
      service_level: 0.95,
      include_seasonality: true
    }
  });
  ```

  ```python Python theme={null}
  planning = stateset.inventory.planning.create(
      planning_type='demand_forecast',
      time_horizon={
          'value': 3,
          'unit': 'months'
      },
      parameters={
          'service_level': 0.95,
          'include_seasonality': True
      }
  )
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "planning_id": "plan_1a2b3c4d5e",
    "planning_type": "demand_forecast",
    "generated_at": "2024-11-15T10:30:00Z",
    "items": [
      {
        "sku": "WIDGET-001",
        "item_name": "Premium Widget",
        "current_stock": 150,
        "forecast": {
          "predicted_demand": 450,
          "confidence_interval": {
            "lower": 380,
            "upper": 520
          },
          "trend": "increasing",
          "seasonality_factor": 1.2
        },
        "recommendations": {
          "reorder_point": 200,
          "safety_stock": 50,
          "economic_order_quantity": 300,
          "max_stock_level": 500,
          "next_order_date": "2024-11-20",
          "next_order_quantity": 300
        },
        "metrics": {
          "turnover_rate": 12.5,
          "stockout_risk": 0.02,
          "carrying_cost": 1250.00,
          "abc_category": "A"
        }
      },
      {
        "sku": "GADGET-002",
        "item_name": "Standard Gadget",
        "current_stock": 75,
        "forecast": {
          "predicted_demand": 180,
          "confidence_interval": {
            "lower": 150,
            "upper": 210
          },
          "trend": "stable",
          "seasonality_factor": 1.0
        },
        "recommendations": {
          "reorder_point": 80,
          "safety_stock": 20,
          "economic_order_quantity": 150,
          "max_stock_level": 250,
          "next_order_date": "2024-11-18",
          "next_order_quantity": 150
        },
        "metrics": {
          "turnover_rate": 8.0,
          "stockout_risk": 0.05,
          "carrying_cost": 450.00,
          "abc_category": "B"
        }
      }
    ],
    "summary": {
      "total_items": 2,
      "total_value": 15750.00,
      "items_below_reorder": 1,
      "urgent_orders": ["GADGET-002"],
      "optimization_savings": 2500.00
    }
  }
  ```
</ResponseExample>

## Planning Types

### Demand Forecast

Predicts future demand using historical sales data and machine learning algorithms.

```javascript theme={null}
const forecast = await stateset.inventory.planning.create({
  planning_type: 'demand_forecast',
  sku: 'WIDGET-001',
  time_horizon: { value: 6, unit: 'months' },
  parameters: {
    include_seasonality: true,
    service_level: 0.98
  }
});
```

### Reorder Optimization

Calculates optimal reorder points and quantities based on demand patterns and costs.

```javascript theme={null}
const reorderPlan = await stateset.inventory.planning.create({
  planning_type: 'reorder_optimization',
  parameters: {
    holding_cost_rate: 0.25,
    ordering_cost: 50,
    lead_time_days: 14
  }
});
```

### Seasonal Planning

Plans inventory levels for seasonal demand variations.

```javascript theme={null}
const seasonalPlan = await stateset.inventory.planning.create({
  planning_type: 'seasonal_planning',
  time_horizon: { value: 1, unit: 'quarters' },
  parameters: {
    service_level: 0.95
  }
});
```

### ABC Analysis

Categorizes inventory based on value and velocity for prioritized management.

```javascript theme={null}
const abcAnalysis = await stateset.inventory.planning.create({
  planning_type: 'abc_analysis',
  location_id: 'loc_warehouse_001'
});
```

## Error Handling

<Warning>
  Planning operations may fail if:

  * Insufficient historical data (less than 30 days)
  * Invalid parameters or constraints
  * SKU not found
  * Location not authorized
</Warning>

```javascript theme={null}
try {
  const planning = await stateset.inventory.planning.create({
    planning_type: 'demand_forecast',
    sku: 'INVALID-SKU'
  });
} catch (error) {
  if (error.code === 'sku_not_found') {
    console.error('SKU does not exist');
  } else if (error.code === 'insufficient_data') {
    console.error('Not enough historical data for forecast');
  }
}
```

## Webhooks

Subscribe to planning events to automate your inventory workflows:

* `inventory.planning.completed` - Planning run completed
* `inventory.reorder.required` - Item below reorder point
* `inventory.stockout.predicted` - Stockout risk detected

## Related Endpoints

* [Create Inventory Item](/api-reference/inventory/create) - Add items to inventory
* [Adjust Inventory](/api-reference/inventory/adjust) - Make stock adjustments
* [Transfer Inventory](/api-reference/inventory/transfer) - Move stock between locations
* [Get Inventory Analytics](/api-reference/inventory/analytics) - View inventory metrics