Inventory Planning

Supply your historical demand series in data, describe your current inventory position and suppliers in inventory_settings, and receive a full plan back. The endpoint forecasts demand automatically — you do not call /forecast separately.

Request Body

{
  "identifier": "SKU-12345",
  "frequency": "M",
  "periods": 6,
  "data": [
    {"date": "2024-01-31", "value": 190},
    {"date": "2024-02-29", "value": 205},
    {"date": "2024-03-31", "value": 210},
    {"date": "2024-04-30", "value": 198},
    {"date": "2024-05-31", "value": 215},
    {"date": "2024-06-30", "value": 208}
  ],
  "inventory_settings": {
    "current_stock": 300,
    "minimum_stock": 100,
    "service_level": 0.95,
    "suppliers": [
      {
        "identifier": "Acme Supply",
        "lead_time_days": 14,
        "minimum_order_quantity": 100,
        "cost_per_unit": 12.50,
        "reliability_score": 0.98
      }
    ]
  }
}

Top-level Parameters

inventory_settings Object

suppliers[] Object

Response

{
  "result": {
    "tenant_context": null,
    "identifier": "SKU-12345",
    "current_stock": 300,
    "minimum_stock": 100,
    "reorder_point": 377.35,
    "safety_stock": 67.35,
    "suppliers": [
      {
        "supplier": "Acme Supply",
        "order_quantity": 200,
        "total_cost": 2500.00,
        "cost_per_unit": 12.5,
        "expected_delivery": "2024-07-14",
        "lead_time_days": 14,
        "minimum_order_quantity": 100,
        "reliability_score": 0.98,
        "lead_time_demand": 210.00,
        "safety_stock": 67.35,
        "reorder_point": 377.35,
        "reason": "$12.50 per unit, reasonable lead time, high reliability"
      }
    ],
    "stock_analysis": {
      "days_of_coverage": 29,
      "stockout_risk": 0.75,
      "next_order_date": "2024-06-30",
      "daily_demand_rate": 7.06,
      "stock_status": "reorder_needed"
    },
    "forecasts": [
      {"period": 1, "date": "2024-07-31", "forecast": 210.00, "lower": 180.00, "upper": 250.00},
      {"period": 2, "date": "2024-08-31", "forecast": 205.00, "lower": 175.00, "upper": 245.00}
    ]
  },
  "meta": {
    "timing": { "validation": 3.2, "planning": 284.1, "total": 288.5 }
  }
}

The response always has this single shape on success (HTTP 200): a result object with the plan and a meta object with timing. There are no alternate success response types.

result Fields

suppliers[] Fields

stock_analysis Fields

stock_status — possible values

The status compares your current_stock against the best supplier's reorder_point and your minimum_stock. They are checked in order, so the first matching row wins.

stockout_risk — possible values

A coarse risk estimate rather than a continuous probability. Let stock_ratio = (current_stock − minimum_stock) / demand over the next 3 periods. The endpoint returns exactly one of these values:

reason — how it is built

When no order is needed, reason is exactly "No order needed - current stock is sufficient". Otherwise it is a comma-separated string assembled from the fragments below (empty fragments are skipped; if none apply it falls back to "standard recommendation").

forecasts[] Fields

The demand forecast the plan is built on. Fields depend slightly on the selected model, but every entry always includes a point forecast and an upper bound — the two values that drive lead-time demand and safety stock.

meta.timing

Server-side timing in milliseconds: validation (request checks), planning (forecast + inventory math), and total (whole request).

422 Validation Error

{
  "message": "The inventory_settings.suppliers field is required.",
  "errors": {
    "inventory_settings.suppliers": [
      "The inventory_settings.suppliers field is required."
    ]
  }
}

500 Planning Error

{
  "error": "Inventory planning failed",
  "time_taken_ms": 42.7
}