Documentation Index
Fetch the complete documentation index at: https://mintlify.com/InnoDev69/StockManager/llms.txt
Use this file to discover all available pages before exploring further.
StockManager ships a two-tier analytics system. A lightweight stats endpoint gives you the numbers you need for a quick dashboard summary — total products, low-stock count, today’s sales, and total inventory value. The full metrics endpoint goes further, computing revenue KPIs with period-over-period comparisons, daily sales-over-time arrays ready for charting, a 7×24 heatmap of sales activity, and an inventory forecast that tells you exactly how many days of stock remain for each product.
Dashboard summary — GET /api/stats
This endpoint requires authentication and returns a single JSON object with the following fields:
| Field | Type | Description |
|---|
products | integer | Total number of products in the catalog |
low_stock | integer | Products where quantity <= min_quantity and quantity > 0 |
sales_today | integer | Number of sales transactions recorded today |
low_stock_list | array | Up to 10 products where quantity <= min_quantity, sorted by quantity ascending |
expire_soon | integer | Products whose expiration_date is on or before 7 days from today (includes already-expired items) |
total_inventory_value | float | Sum of quantity × price for all active products |
low_stock_list contains id, name, sku (barcode), and stock.
curl http://localhost:5000/api/stats
{
"products": 248,
"low_stock": 7,
"sales_today": 34,
"low_stock_list": [
{ "id": 12, "name": "Orange Juice 1L", "sku": "7501000000012", "stock": 2 }
],
"expire_soon": 3,
"total_inventory_value": 14820.50
}
Full analytics — GET /api/metrics
The metrics endpoint computes a rich dataset over a configurable time window and always compares the selected period against an equal-length previous period to generate percentage change figures.
Period selection
| Parameter | Type | Description |
|---|
period | integer | Preset window: 7, 30, 90, or 365 days back from today (default: 7) |
from | YYYY-MM-DD | Custom start date — overrides period when both from and to are provided |
to | YYYY-MM-DD | Custom end date |
from and to are both present they take precedence over period. The previous comparison period is automatically computed as an equal-length window ending the day before from.
KPIs
The kpis object in the response contains the following fields:
| Field | Description |
|---|
revenue | Total revenue for the selected period |
totalSales | Number of sale transactions |
avgTicket | Average revenue per transaction (revenue / totalSales) |
unitsSold | Total units sold across all products |
revenueChange | % change in revenue vs previous period |
salesChange | % change in transaction count vs previous period |
ticketChange | % change in average ticket vs previous period |
unitsChange | % change in units sold vs previous period |
Sales over time
salesOverTime provides three parallel arrays designed to feed directly into a line or bar chart:
labels — display strings for each day ("Mon" / "14/07" depending on period length ≤7 or >7)revenue — revenue total for each daysales — transaction count for each day
Days with no sales are included with 0 values so chart libraries always receive a complete, contiguous series.
Top products
topProducts is an array of up to 10 best-selling products within the period, sorted by units sold descending:
[
{ "id": 34, "name": "Granola Bar", "sku": "7501000000034", "units": 143, "revenue": 127.27 }
]
Sales heatmap
heatmap.data is a 7×24 matrix (rows = days Mon–Sun, columns = hours 0–23). Each cell contains an estimated integer number of sales for that day-of-week / hour combination, derived by distributing the actual weekly and hourly totals proportionally. Use this to identify peak trading times.
{
"heatmap": {
"data": [[0, 0, 0, 1, 3, ...], ...],
"days": ["Lun", "Mar", "Mié", "Jue", "Vie", "Sáb", "Dom"],
"hours": [0, 1, 2, ..., 23]
}
}
Inventory forecast
inventoryForecast ranks active products by how many days of stock remain at their current daily sales rate. Products with no sales in the period are excluded (they have no calculable daily average). Each entry contains:
| Field | Description |
|---|
id / name / sku | Product identifiers |
currentStock | Current quantity on hand |
minStock | Configured minimum quantity |
unitsSold | Units sold during the period |
dailyAverage | Average units sold per day |
daysRemaining | Estimated days until stock reaches 0 |
rotation | unitsSold / currentStock — how many times stock turned over |
status | "normal", "warning" (≤7 days), or "danger" (≤3 days) |
criticalStocks top-level key is a further-filtered subset containing only "danger" status items.
Trend line
trendLine contains the same labels array as salesOverTime plus a values array of 7-day moving averages over the daily revenue. The first window - 1 entries are null (not enough prior data), allowing chart libraries to display the trend line only where it is statistically meaningful.
Additional insights
The insights object surfaces three human-readable findings computed from the same dataset:
bestDay — the weekday with the highest revenue (name + revenue)peakHour — the hour of day with the most sales (0–23 integer)topProduct — name and unit count of the best-selling producttrend — a plain-language sentence describing revenue change vs the previous period
Never-sold products — GET /api/never-sold
This supplementary endpoint returns all active products that have never appeared in any sale detail record, making it easy to identify dead stock.
{
"products": [
{ "id": 77, "name": "Specialty Tea", "sku": "PRD000077", "stock": 50, "price": 3.49 }
]
}
Example request
curl "http://localhost:5000/api/metrics?period=30"
{
"kpis": {
"revenue": 8420.75,
"totalSales": 310,
"avgTicket": 27.16,
"unitsSold": 1840,
"revenueChange": 12.4,
"salesChange": 8.1,
"ticketChange": 3.9,
"unitsChange": 10.2
},
"salesOverTime": {
"labels": ["15/06", "16/06", "..."],
"revenue": [220.50, 310.00, "..."],
"sales": [8, 11, "..."]
},
"topProducts": [...],
"heatmap": { "data": [...], "days": [...], "hours": [...] },
"inventoryForecast": [...],
"criticalStocks": [...],
"trendLine": { "labels": [...], "values": [...] },
"period": { "start": "2025-06-15", "end": "2025-07-14", "days": 30 }
}
Use period=7 for operational dashboards that refresh frequently and period=30 or period=90 for monthly or quarterly business reviews. Pass explicit from and to parameters when you need to compare custom date ranges such as a promotional event window.