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

{
  "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
​
parameters
object
Planning-specific parameters

​
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
​
summary
object
Overall planning summary
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
    }
  }'

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