# Demand Forecasting

Daily, per-product sales forecasts for the next 7 to 28 days, plus what a
store does with a forecast: stockout alerts, a replenishment list with
purchase orders, an overstock report with markdown suggestions, a promo
calendar, and manual overrides for the things no model can know.

Available on the Growth and Scale plans. Works for WooCommerce, custom
integrations and Shopify stores. Every `/forecast/*` endpoint accepts the
dashboard login or the account's secret API key (`X-API-Key`), which is how the
Shopify app drives it. Shopify forecasts count order lines until the app has
recorded unit quantities on most recent orders, then switch to units
automatically.

## How it works

Every night the system trains a gradient-boosting model (LightGBM) on your
store's own order history, per product and per day, and publishes a forecast
with three numbers per day: the expected value (p50) and a low/high band
(p10/p90). Stores below the data threshold (roughly 60 days of orders and 500
order lines) get statistical fallbacks per product instead; every number is
labeled with the method that produced it.

The model reads, per target day:

- **Calendar**: weekday, holidays for your country, Black Friday week,
  December peak, Valentine's, and payday windows (in Bulgaria: the 25th
  through the 5th).
- **Weather**: temperature, rain and snow for your store's location
  (Open-Meteo), useful for seasonal assortments.
- **Sales dynamics**: lags, rolling averages, days-since-sale,
  add-to-cart and click leading indicators.
- **Promo calendar**: your planned promotions (see below).

## Accuracy, honestly measured

Every run records its 7-day-ahead prediction; once reality catches up, the
dashboard shows:

- **WAPE**: the average error of recent forecasts vs. what really sold.
- **p90 coverage**: what share of days landed under the high estimate
  (target: 90%). This is what makes the "safe" ordering quantity trustworthy.
- **vs. naive**: how much better the model is than "same as this day last
  week". If it isn't, the dashboard says so.

Nothing shows until enough predictions have matured, so the dashboard never
reports fake accuracy on day one.

## Replenishment and purchase orders

The Replenishment page answers "what do I order, how much, and by when":
stockout dates from the forecast, order-by dates from the lead time, and a
suggested quantity computed at the p90 (safe) level.

With suppliers configured (Suppliers page), each product uses its supplier's
real lead time, quantities round up to case packs and clamp to minimum order
quantities, and selected rows turn into a purchase order per supplier. Edit
the draft, then email it to the supplier or download it as CSV.

## Overstock and markdowns

The Overstock page lists stock the forecast says will not sell before season
end, with weeks of cover and aging. Where your price history supports an
honest elasticity estimate, it also shows a suggested discount depth with its
projected clear-through.

If your catalog feed includes a `cost` field (see the
[data checklist](data-quality-checklist.md)), suggestions never go below
cost, the page shows the cash tied up in dead stock, and replenishment rows
carry an expected margin.

## Promo calendar and manual overrides

Tell the forecast about planned promotions (dates, expected discount,
store-wide or specific products) on the Promo calendar page. The model treats
promo days as their own signal and learns your store's promo lift from your
own history. The first events mostly teach it for the ones after.

Manual overrides are for facts outside any data: a TV spot airing Tuesday, a
recalled batch. A multiplier scales the whole forecast band for chosen days;
an absolute value pins the daily quantity. Overridden days are marked, so a
merchant's number is never mistaken for the model's.

## Alerts and the weekly digest

Opt-in emails, in your account language:

- **Nightly alerts**: products about to run out (with stock left and daily
  rate) and products with a demand spike ahead.
- **Weekly digest**: Monday morning, at most three concrete actions:
  "Order 240 units of X today", "Shoppers searched Y and found nothing",
  "Z won't clear this season".

## Getting started

1. Send order history and keep `stock_qty` fresh on catalog pushes. See the
   [data checklist](data-quality-checklist.md). WooCommerce stores get all of
   this from the [plugin](woocommerce-plugin.md) automatically.
2. In the dashboard, open **Demand > Settings**, enable forecasting, and set
   your store's city (for weather and country holidays).
3. Run the first forecast from the Demand page, or wait for the nightly run.
