StateSet API Docs

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

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

POST

api

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

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

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

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

Create Inventory Item - Add items to inventory
Adjust Inventory - Make stock adjustments
Transfer Inventory - Move stock between locations
Get Inventory Analytics - View inventory metrics

Inventory Analytics List Packing List

​Request Body

​Response

​Planning Types

​Demand Forecast

​Reorder Optimization

​Seasonal Planning

​ABC Analysis

​Error Handling

​Webhooks

​Related Endpoints

Request Body

Response

Planning Types

Demand Forecast

Reorder Optimization

Seasonal Planning

ABC Analysis

Error Handling

Webhooks

Related Endpoints