Inventory Planning

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

POST /api/v1/inventory/planning

cURL

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
    }
  }'

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
  }
});

planning = stateset.inventory.planning.create(
    planning_type='demand_forecast',
    time_horizon={
        'value': 3,
        'unit': 'months'
    },
    parameters={
        'service_level': 0.95,
        'include_seasonality': True
    }
)

Response

{
  "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
  }
}

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

Request Body

planning_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

sku · string

Specific SKU to plan for. If omitted, plans all inventory items.

location_id · string

Location ID for location-specific planning

time_horizon · object

Planning time horizon

Show properties

value · integer · required

Number of time units

unit · string · required

Time unit: days, weeks, months, quarters

parameters · object

Planning-specific parameters

Show properties

service_level · number

Target service level (0-1). Default: 0.95

lead_time_days · integer

Supplier lead time in days

holding_cost_rate · number

Annual holding cost as percentage of item value

ordering_cost · number

Fixed cost per order

include_seasonality · boolean

Include seasonal patterns in forecast. Default: true

Response

planning_id · string

Unique identifier for this planning run

planning_type · string

Type of planning performed

generated_at · string

ISO 8601 timestamp of when the plan was generated

items · array

Array of planning results per inventory item

Show properties

sku · string

SKU of the inventory item

item_name · string

Name of the inventory item

current_stock · integer

Current available stock level

forecast · object

Demand forecast details

Show properties

predicted_demand · number

Predicted demand for the time horizon

confidence_interval · object

95% confidence interval

Show properties

lower · number

Lower bound of prediction

upper · number

Upper bound of prediction

trend · string

Demand trend: increasing, decreasing, stable

seasonality_factor · number

Current seasonal adjustment factor

recommendations · object

Planning recommendations

Show properties

reorder_point · integer

Recommended reorder point

safety_stock · integer

Recommended safety stock level

economic_order_quantity · integer

Optimal order quantity (EOQ)

max_stock_level · integer

Maximum recommended stock level

next_order_date · string

Recommended date for next order

next_order_quantity · integer

Recommended quantity for next order

metrics · object

Performance metrics

Show properties

turnover_rate · number

Annual inventory turnover rate

stockout_risk · number

Probability of stockout (0-1)

carrying_cost · number

Estimated annual carrying cost

abc_category · string

ABC classification: A, B, or C

summary · object

Overall planning summary

Show properties

total_items · integer

Number of items planned

total_value · number

Total inventory value

items_below_reorder · integer

Items currently below reorder point

urgent_orders · array

List of SKUs requiring immediate reorder

optimization_savings · number

Estimated annual savings from optimization

cURL

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
    }
  }'

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
  }
});

planning = stateset.inventory.planning.create(
    planning_type='demand_forecast',
    time_horizon={
        'value': 3,
        'unit': 'months'
    },
    parameters={
        'service_level': 0.95,
        'include_seasonality': True
    }
)

Response

{
  "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
  }
}

Planning Types

Demand Forecast

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

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.

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.

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.

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

Error Handling

Planning operations may fail if:

• Insufficient historical data (less than 30 days)
• Invalid parameters or constraints
• SKU not found
• Location not authorized

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 - Add items to inventory
• Adjust Inventory - Make stock adjustments
• Transfer Inventory - Move stock between locations
• Get Inventory Analytics - View inventory metrics