The Forecast API provides intelligent forecasting capabilities to help optimize inventory management through predictive analytics.
All forecast endpoints require authentication and are accessible only to Manager and Admin roles.
Demand Forecast Get demand forecast for a specific product based on historical consumption patterns.
Access: Private (Manager/Admin)Query Parameters MongoDB ObjectId of the product
Number of months to forecast (1-12)
Response Daily consumption rate (units per day)
Monthly projections Month identifier (e.g., “Month 1”)
Projected demand for the month
Projected remaining stock
Whether reorder is needed (stock less than 10)
Forecast period description
Example Request GET /api/forecast/demand?productId=673ab12c5f8e9a001234abcd & months = 3 Authorization: Bearer < toke n >
Example Response { "success" : true , "message" : "Demand forecast generated successfully" , "data" : { "product" : { "id" : "673ab12c5f8e9a001234abcd" , "productName" : "Fresh Milk" , "category" : "Dairy" , "currentQuantity" : 85 , "sku" : "DA-001" }, "consumptionRate" : 2.5 , "forecast" : [ { "month" : "Month 1" , "projectedDemand" : 75 , "projectedStock" : 10 , "needsReorder" : true }, { "month" : "Month 2" , "projectedDemand" : 150 , "projectedStock" : 0 , "needsReorder" : true }, { "month" : "Month 3" , "projectedDemand" : 225 , "projectedStock" : 0 , "needsReorder" : true } ], "period" : "3 months" } }
Products require at least 7 days of historical data for accurate forecasting. If insufficient data exists, the endpoint returns a message indicating this limitation.
Category Demand Forecast Get aggregated demand forecast for all products in a category.
Access: Private (Manager/Admin)Path Parameters Category name (case-insensitive)
Query Parameters Number of months to forecast
Response Number of items in category
Total current quantity across all items
Average daily consumption rate for category
Monthly projections for category
Example Request GET /api/forecast/demand/category/Dairy?months= 2 Authorization: Bearer < toke n >
Example Response { "success" : true , "message" : "Category demand forecast generated successfully" , "data" : { "category" : "Dairy" , "itemCount" : 5 , "currentTotalQuantity" : 420 , "avgConsumptionRate" : 3.2 , "forecast" : [ { "month" : "Month 1" , "projectedDemand" : 480 , "projectedStock" : 0 }, { "month" : "Month 2" , "projectedDemand" : 960 , "projectedStock" : 0 } ], "period" : "2 months" } }
Reorder Suggestions Get intelligent reorder suggestions based on consumption rates and lead times.
Access: Private (Manager/Admin)Query Parameters Lead time in days for receiving orders
Safety stock multiplier (e.g., 1.5 = 150% of lead time demand)
Response List of products that need reordering Product details (id, productName, category, sku, supplier)
Calculated reorder point threshold
Recommended order quantity (30 days worth)
Urgency level: CRITICAL (out of stock), HIGH (below half reorder point), MEDIUM
Days until stockout at current consumption rate
Number of reorder suggestions
Configuration parameters used
Example Request GET /api/forecast/reorder-suggestions?leadTime= 5 & safetyStock = 2.0 Authorization: Bearer < toke n >
Example Response { "success" : true , "message" : "Reorder suggestions generated successfully" , "data" : { "suggestions" : [ { "product" : { "id" : "673ab12c5f8e9a001234abcd" , "productName" : "Chicken Breast" , "category" : "Meat" , "sku" : "MT-015" , "supplier" : "Fresh Poultry Co" }, "currentQuantity" : 0 , "reorderPoint" : 15 , "suggestedOrderQuantity" : 90 , "urgency" : "CRITICAL" , "consumptionRate" : 3.0 , "estimatedStockoutDays" : 0 }, { "product" : { "id" : "673ab12c5f8e9a001234abce" , "productName" : "Yogurt" , "category" : "Dairy" , "sku" : "DA-008" , "supplier" : "Local Dairy Farm" }, "currentQuantity" : 8 , "reorderPoint" : 20 , "suggestedOrderQuantity" : 60 , "urgency" : "HIGH" , "consumptionRate" : 2.0 , "estimatedStockoutDays" : 4 } ], "count" : 2 , "parameters" : { "leadTimeDays" : 5 , "safetyStockMultiplier" : 2.0 } } }
CRITICAL urgency items are out of stock and should be ordered immediately. HIGH urgency items are below 50% of their reorder point.
Stock Trends Get historical stock trend analysis for a product.
Access: Private (Manager/Admin)Query Parameters MongoDB ObjectId of the product
Analysis period: “7days”, “30days”, or “90days”
Response Historical trend data points Date in YYYY-MM-DD format
Estimated quantity on that date
Whether this is the current date point
Trend analysis Daily consumption velocity
Overall trend: “increasing”, “decreasing”, or “stable”
Example Request GET /api/forecast/stock-trends?productId=673ab12c5f8e9a001234abcd & period = 30days Authorization: Bearer < toke n >
Example Response { "success" : true , "message" : "Stock trends fetched successfully" , "data" : { "product" : { "id" : "673ab12c5f8e9a001234abcd" , "productName" : "Fresh Milk" , "category" : "Dairy" , "currentQuantity" : 85 }, "trends" : [ { "date" : "2025-02-01" , "estimatedQuantity" : 160 }, { "date" : "2025-02-06" , "estimatedQuantity" : 148 }, { "date" : "2025-02-11" , "estimatedQuantity" : 135 }, { "date" : "2025-02-16" , "estimatedQuantity" : 123 }, { "date" : "2025-02-21" , "estimatedQuantity" : 110 }, { "date" : "2025-02-26" , "estimatedQuantity" : 98 }, { "date" : "2025-03-03" , "estimatedQuantity" : 85 , "isCurrent" : true } ], "analysis" : { "velocityPerDay" : 2.5 , "trend" : "decreasing" , "period" : "30days" } } }
Expiry Forecast Predict items likely to expire with remaining stock, helping minimize waste.
Access: Private (Manager/Admin)Response Items at risk of expiring with stock remaining Product details (id, productName, category, sku)
Days remaining until expiry
projectedQuantityAtExpiry
Estimated quantity that will remain at expiry
Percentage of current stock likely to be wasted
Risk level: HIGH (greater than 50% wastage), MEDIUM (25-50%), LOW (less than 25%)
Actionable recommendation
Total number of items at risk
Number of high-risk items
Example Request GET /api/forecast/expiry-forecast Authorization: Bearer < toke n >
Example Response { "success" : true , "message" : "Expiry forecast generated successfully" , "data" : { "forecasts" : [ { "product" : { "id" : "673ab12c5f8e9a001234abcd" , "productName" : "Strawberries" , "category" : "Produce" , "sku" : "PR-025" }, "currentQuantity" : 100 , "expiryDate" : "2025-03-08T00:00:00.000Z" , "daysUntilExpiry" : 5 , "consumptionRate" : 8.5 , "projectedQuantityAtExpiry" : 58 , "wastagePercentage" : 58.0 , "riskLevel" : "HIGH" , "recommendation" : "Consider promotional pricing or immediate sale" }, { "product" : { "id" : "673ab12c5f8e9a001234abce" , "productName" : "Cheese" , "category" : "Dairy" , "sku" : "DA-012" }, "currentQuantity" : 45 , "expiryDate" : "2025-03-15T00:00:00.000Z" , "daysUntilExpiry" : 12 , "consumptionRate" : 3.0 , "projectedQuantityAtExpiry" : 9 , "wastagePercentage" : 20.0 , "riskLevel" : "LOW" , "recommendation" : "Current consumption rate is acceptable" } ], "count" : 2 , "highRiskCount" : 1 } }
Use high-risk expiry forecasts to plan promotional campaigns, discounts, or alternative distribution channels to minimize waste and maximize revenue recovery.
Error Responses All forecast endpoints return standard error responses:
Status Code Description 400 Bad Request - Missing or invalid parameters 401 Unauthorized - Invalid or missing token 403 Forbidden - Insufficient permissions (Worker role) 404 Not Found - Product or category not found 500 Internal Server Error - Server-side error
Example Error Response { "success" : false , "message" : "Product ID is required" }
Analytics API Demand forecasting and business intelligence
Inventory API Inventory management endpoints
Alerts API Low stock and expiry alerts
Demand Forecasting Feature Learn about forecasting algorithms