List products with sales and stock performance
Returns a paginated, searchable list of products (the catalog) where each row is enriched with sales-performance and stock metrics: units sold, gross and net sales (revenue), gross margin and margin %, monthly sales, average selling price, stock value, on-hand quantity, and merchandising tags (e.g. overstock / slow-mover). Use this to review product performance, find best-selling / top-selling products by revenue or units, spot overstock and slow-movers, or resolve a product identifier. To rank best-sellers, sort with sortBy + sortDirection=desc: sortBy=totalNetSales (net revenue), sortBy=totalGrossSales (gross revenue), or sortBy=totalUnitsSold (units sold); the default sortBy=name returns products alphabetically, NOT by performance. Filter by brand or free-text search on the product name. (For an AI-ranked list of which products to restock, rebalance, or mark down, use GET /intelligence/decision-vectors; for stock-out urgency see GET /inventory/risks.) The KPI columns are read from the gold dim_product_summary tables, which are pre-aggregated PER time_period (~13 rows per product, one per period). The period query param selects the window (default LAST_30_DAYS) and the response always reflects exactly one period — a read that did not pin a single period would fan out and return inflated counts and totals.
Authorizations
User session token issued by NextAuth. For human users accessing Solya via the web application.
Query Parameters
Page number, 1-indexed (default: 1)
1 <= x <= 9007199254740991Number of items per page, max 100 (default: 20)
1 <= x <= 100Case-insensitive substring search query
Pre-aggregated time window to read product KPIs for (defaults to LAST_30_DAYS). The gold dim_product_summary tables hold one row per product per time_period; this selects which window's aggregates (sales, units, margin, stock) are returned. Choosing a different period changes the metric values, not the set of products.
LAST_7_DAYS, LAST_30_DAYS, LAST_90_DAYS, LAST_6_MONTHS, LAST_12_MONTHS, THIS_MONTH, THIS_QUARTER, THIS_YEAR, YEAR_TO_DATE, LAST_MONTH, LAST_QUARTER, LAST_YEAR, ALL_TIME Column to sort by. Defaults to 'name' (alphabetical). For best-selling / top-selling products, use a sales metric: 'totalNetSales' (net revenue), 'totalGrossSales' (gross revenue), or 'totalUnitsSold' (units sold), combined with sortDirection=desc. Other metrics: 'totalQuantity' (stock on hand), 'averagePrice', 'monthlySales', 'stockValue', 'totalDiscount', 'totalCogs', 'totalGrossMargin', 'totalTransactions', 'avgGrossMarginPct', 'avgSellingPrice', 'variantCount', 'shopCount', plus the 'brandName' and 'family' dimensions.
name, brandName, family, totalQuantity, averagePrice, monthlySales, stockValue, totalGrossSales, totalNetSales, totalUnitsSold, totalDiscount, totalCogs, totalGrossMargin, totalTransactions, avgGrossMarginPct, avgSellingPrice, variantCount, shopCount Sort direction: 'asc' or 'desc'. Defaults to 'asc'. Use 'desc' with a sales-metric sortBy (e.g. totalNetSales) to rank best-sellers first.
asc, desc