Skip to main content

​
Overview

The Analytics API provides advanced business intelligence features including demand forecasting, FEFO (First Expired, First Out) ordering recommendations, top-selling products analysis, and notification alerts. All endpoints require authentication and Manager/Admin role. Access: All analytics endpoints require Private (Manager/Admin only) access.

​
Demand Forecast

Get demand forecasting data for top products with 7-day projections. Access: Private (Manager/Admin only)

​
Query Parameters

​
limit
number
default:"5"
Number of products to include in forecast

​
Response

​
forecasts
array
Array of product forecasts
​
product
object
​
id
string
Product ID
​
name
string
Product name
​
category
string
Product category
​
sku
string
Stock Keeping Unit
​
currentQuantity
number
Current stock quantity
​
forecast
array
7-day forecast array with daily projections
​
day
number
Day number (1-7)
​
date
string
Date in YYYY-MM-DD format
​
projectedQuantity
number
Projected quantity for that day
​
trend
string
Trend indicator: stable, normal, or critical
​
estimatedDailyConsumption
number
Estimated daily consumption rate

​
Example Response

{
  "success": true,
  "message": "Demand forecast data fetched successfully",
  "data": {
    "forecasts": [
      {
        "product": {
          "id": "65a1234567890abcdef12345",
          "name": "Organic Apples",
          "category": "Fruits",
          "sku": "FRT-001",
          "currentQuantity": 150
        },
        "forecast": [
          {
            "day": 1,
            "date": "2024-01-16",
            "projectedQuantity": 145,
            "trend": "stable"
          },
          {
            "day": 2,
            "date": "2024-01-17",
            "projectedQuantity": 140,
            "trend": "stable"
          },
          {
            "day": 7,
            "date": "2024-01-22",
            "projectedQuantity": 8,
            "trend": "critical"
          }
        ],
        "estimatedDailyConsumption": 5.2
      }
    ]
  }
}
The forecast algorithm assumes steady consumption based on historical quantity changes. Critical trend is flagged when projected quantity falls below 10 units.

​
FEFO Ordering

Get First Expired, First Out (FEFO) ordering recommendations based on expiry dates. Access: Private (Manager/Admin only)

​
Query Parameters

​
limit
number
default:"10"
Number of items to return

​
Response

​
items
array
Array of items sorted by expiry date (nearest first)
​
id
string
Item ID
​
productName
string
Product name
​
category
string
Product category
​
sku
string
Stock Keeping Unit
​
quantity
number
Current quantity
​
expiryDate
string
Expiry date
​
daysUntilExpiry
number
Days until expiration
​
urgency
string
Urgency level: critical (≤3 days), high (≤7 days), medium (≤14 days), or low (>14 days)
​
supplier
string
Supplier name
​
count
number
Number of items returned

​
Example Response

{
  "success": true,
  "message": "FEFO ordering fetched successfully",
  "data": {
    "items": [
      {
        "id": "65a1234567890abcdef12345",
        "productName": "Fresh Milk",
        "category": "Dairy",
        "sku": "DRY-015",
        "quantity": 25,
        "expiryDate": "2024-01-18T00:00:00.000Z",
        "daysUntilExpiry": 2,
        "urgency": "critical",
        "supplier": "Dairy Fresh Co"
      },
      {
        "id": "65a9876543210fedcba98765",
        "productName": "Greek Yogurt",
        "category": "Dairy",
        "sku": "DRY-022",
        "quantity": 40,
        "daysUntilExpiry": 5,
        "urgency": "high",
        "supplier": "Dairy Fresh Co"
      }
    ],
    "count": 2
  }
}
Only non-expired items with quantity > 0 are included in FEFO ordering.

​
Top Selling Products

Get top-selling products based on sales velocity analysis. Access: Private (Manager/Admin only)

​
Query Parameters

​
limit
number
default:"5"
Number of products to return

​
Response

​
products
array
Array of top-selling products
​
id
string
Product ID
​
productName
string
Product name
​
category
string
Product category
​
sku
string
Stock Keeping Unit
​
currentQuantity
number
Current stock quantity
​
estimatedSold
number
Estimated units sold
​
salesVelocity
number
Sales velocity (units per day)
​
daysSincePurchase
number
Days since initial purchase
​
count
number
Number of products returned

​
Example Response

{
  "success": true,
  "message": "Top selling products fetched successfully",
  "data": {
    "products": [
      {
        "id": "65a1234567890abcdef12345",
        "productName": "Organic Apples",
        "category": "Fruits",
        "sku": "FRT-001",
        "currentQuantity": 150,
        "estimatedSold": 75,
        "salesVelocity": 5.4,
        "daysSincePurchase": 14
      }
    ],
    "count": 1
  }
}
Sales velocity is calculated based on estimated consumption over time. Higher velocity indicates faster-moving products.

​
Notification Alerts

Get comprehensive notification-style alerts for inventory issues. Access: Private (Manager/Admin only)

​
Query Parameters

​
limit
number
default:"10"
Maximum number of alerts to return

​
Response

​
alerts
array
Array of alerts sorted by severity
​
id
string
Item ID
​
type
string
Alert type: expired, expiring_soon, out_of_stock, or low_stock
​
severity
string
Severity level: critical, high, medium, or low
​
productName
string
Product name
​
category
string
Product category
​
message
string
Human-readable alert message
​
timestamp
string
Alert timestamp
​
count
number
Total number of alerts

​
Example Response

{
  "success": true,
  "message": "Notification alerts fetched successfully",
  "data": {
    "alerts": [
      {
        "id": "65a1234567890abcdef12345",
        "type": "expired",
        "severity": "critical",
        "productName": "Fresh Milk",
        "category": "Dairy",
        "message": "Fresh Milk has expired 3 days ago",
        "timestamp": "2024-01-15T10:30:00.000Z"
      },
      {
        "id": "65a9876543210fedcba98765",
        "type": "expiring_soon",
        "severity": "high",
        "productName": "Greek Yogurt",
        "category": "Dairy",
        "message": "Greek Yogurt is expiring in 2 days",
        "timestamp": "2024-01-15T10:30:00.000Z"
      },
      {
        "id": "65a5555555555555555555555",
        "type": "out_of_stock",
        "severity": "high",
        "productName": "Bananas",
        "category": "Fruits",
        "message": "Bananas is out of stock",
        "timestamp": "2024-01-15T10:30:00.000Z"
      },
      {
        "id": "65a6666666666666666666666",
        "type": "low_stock",
        "severity": "medium",
        "productName": "Oranges",
        "category": "Fruits",
        "message": "Oranges is running low (7 units remaining)",
        "timestamp": "2024-01-15T10:30:00.000Z"
      }
    ],
    "count": 4
  }
}

​
Alert Types

TypeDescriptionSeverity
expiredProduct has passed expiry datecritical
expiring_soonExpires within 7 dayshigh (≤3 days), medium (4-7 days)
out_of_stockQuantity is 0high
low_stockQuantity less than 10high (below 5), medium (5-9)
Critical and high severity alerts require immediate attention to prevent product waste or stockouts.

Build docs developers (and LLMs) love

Get started for freeTalk to us