Overview
The Alert System API provides real-time monitoring of inventory issues including low stock, expiring products, expired items, and out-of-stock situations. All endpoints require authentication.
Low Stock Alerts
Get items with stock levels below the threshold.
Access: Private (all authenticated users)
Query Parameters
Stock threshold (uses LOW_STOCK_THRESHOLD env variable if not provided)
Response
Array of low stock itemsHIGH if quantity ≤ threshold/2, otherwise MEDIUM
Alert message with current stock level
Number of low stock items
Example Response
{
"success": true,
"message": "Low stock alerts fetched successfully",
"data": {
"alerts": [
{
"_id": "65a1234567890abcdef12345",
"productName": "Organic Apples",
"category": "Fruits",
"sku": "FRT-001",
"quantity": 4,
"expiryDate": "2024-02-15T00:00:00.000Z",
"supplier": "Fresh Farms Ltd",
"alertType": "low_stock",
"severity": "HIGH",
"message": "Only 4 units left in stock"
}
],
"count": 1,
"threshold": 10
}
}
Expiring Soon Alerts
Get items expiring within the specified number of days.
Access: Private (all authenticated users)
Query Parameters
Number of days to look ahead (uses EXPIRY_ALERT_DAYS env variable if not provided)
Response
Array of expiring items sorted by expiry dateAlert type: expiring_soon
CRITICAL (≤1 day), HIGH (≤3 days), MEDIUM (≤5 days), or LOW (>5 days)
Alert message with days until expiry
Example Response
{
"success": true,
"message": "Expiring soon alerts fetched successfully",
"data": {
"alerts": [
{
"_id": "65a1234567890abcdef12345",
"productName": "Fresh Milk",
"category": "Dairy",
"quantity": 25,
"expiryDate": "2024-01-18T00:00:00.000Z",
"alertType": "expiring_soon",
"severity": "HIGH",
"daysUntilExpiry": 2,
"message": "Expires in 2 days"
}
],
"count": 1,
"days": 7
}
}
Expired Items Alerts
Get items that have passed their expiry date.
Access: Private (all authenticated users)
Response
Array of expired items sorted by expiry date (oldest first)Alert message with days expired
Example Response
{
"success": true,
"message": "Expired items alerts fetched successfully",
"data": {
"alerts": [
{
"_id": "65a1234567890abcdef12345",
"productName": "Old Cheese",
"category": "Dairy",
"quantity": 5,
"expiryDate": "2024-01-10T00:00:00.000Z",
"alertType": "expired",
"severity": "CRITICAL",
"daysExpired": 5,
"message": "Expired 5 days ago"
}
],
"count": 1
}
}
Out of Stock Alerts
Get items with zero quantity.
Access: Private (all authenticated users)
Response
Array of out-of-stock items Number of out-of-stock items
Example Response
{
"success": true,
"message": "Out of stock alerts fetched successfully",
"data": {
"alerts": [
{
"_id": "65a1234567890abcdef12345",
"productName": "Bananas",
"category": "Fruits",
"sku": "FRT-015",
"quantity": 0,
"alertType": "out_of_stock",
"severity": "HIGH",
"message": "Out of stock - Immediate restocking required"
}
],
"count": 1
}
}
Critical Alerts
Get all critical alerts combined (expired, expiring in ≤3 days, out of stock, critically low stock below 5 units).
Access: Private (all authenticated users)
Response
Combined array of critical alerts sorted by priorityAlert type: expired, expiring_critical, out_of_stock, or critical_low_stock
Priority ranking (1 = highest)
Total number of critical alerts
Count of items expiring in ≤3 days
Count of out-of-stock items
Count of items with less than 5 units
Example Response
{
"success": true,
"message": "Critical alerts fetched successfully",
"data": {
"alerts": [
{
"productName": "Old Cheese",
"alertType": "expired",
"severity": "CRITICAL",
"priority": 1,
"message": "Expired 5 days ago"
},
{
"productName": "Fresh Milk",
"alertType": "expiring_critical",
"severity": "CRITICAL",
"priority": 2,
"daysUntilExpiry": 2,
"message": "Expires in 2 days"
}
],
"count": 2,
"breakdown": {
"expired": 1,
"expiringSoon": 1,
"outOfStock": 0,
"criticalLowStock": 0
}
}
}
Category-Specific Alerts
Get all alerts for a specific category.
Access: Private (all authenticated users)
Path Parameters
Category name (case-insensitive)
Response
Array of items with their alertsArray of alert objects for this item Number of items with alerts
Example Response
{
"success": true,
"message": "Alerts for Dairy category fetched successfully",
"data": {
"category": "Dairy",
"alerts": [
{
"_id": "65a1234567890abcdef12345",
"productName": "Fresh Milk",
"category": "Dairy",
"quantity": 25,
"alerts": [
{
"type": "expiring_soon",
"severity": "HIGH",
"message": "Expires in 2 days"
}
]
},
{
"_id": "65a9876543210fedcba98765",
"productName": "Cheese",
"category": "Dairy",
"quantity": 3,
"alerts": [
{
"type": "low_stock",
"severity": "HIGH",
"message": "Only 3 units left"
}
]
}
],
"count": 2
}
}
Alert Summary
Get dashboard summary of all alert counts.
Access: Private (all authenticated users)
Response
Count of items expiring within 7 days
Count of out-of-stock items
Count of low stock items (quantity < 10)
Count of critical alerts (expired + out of stock)
Example Response
{
"success": true,
"message": "Alert summary fetched successfully",
"data": {
"summary": {
"totalAlerts": 15,
"breakdown": {
"expired": 2,
"expiringSoon": 4,
"outOfStock": 3,
"lowStock": 6
},
"criticalCount": 5
}
}
}
Severity Levels
| Severity | Description | Use Case |
|---|
CRITICAL | Requires immediate action | Expired items, items expiring in ≤1 day |
HIGH | Urgent attention needed | Out of stock, very low stock (below 5), expiring in ≤3 days |
MEDIUM | Should be addressed soon | Low stock (5-9), expiring in 4-5 days |
LOW | For awareness | Expiring in 6-7 days |
Always prioritize CRITICAL and HIGH severity alerts to prevent product waste and stockouts.