E-commerce & Retail
Demand Forecasting API
Every stockout and every markdown is a forecast that was wrong. The question is not whether you forecast, but whether the forecast knows how uncertain it is.
- Retailers
- Marketplaces
- Inventory software vendors
- Wholesalers
- Direct-to-consumer brands
What your customers would see
example interfaceMockupIllustrative mockup of the interface we would build. Figures shown are examples, not results from a live deployment.
The problem this solves
Most replenishment still runs on a moving average with a safety-stock multiplier that someone set years ago. For stable, high-volume lines that is defensible. It falls apart on the long tail, on new products with no history, and on anything whose demand is driven by promotion, weather or a competitor going out of stock.
The deeper problem is that a point forecast is the wrong output. A buyer deciding how much to hold does not need a single number; they need the shape of the distribution, because the cost of being short and the cost of being long are rarely symmetric. A fashion line and a replacement filter have opposite error economics, and a single forecast number cannot express that.
Forecasting at SKU and location granularity also means forecasting mostly zeros. A large share of store-SKU combinations sell nothing in a given week, and models fitted on aggregate behaviour handle that badly. Intermittent demand needs its own treatment, and the honest version of this build says so up front.
Who buys this
Retailers, Marketplaces, Inventory software vendors, Wholesalers, Direct-to-consumer brands
What the API returns
What comes back
- Forecast quantity per SKU, per location, per period
- Prediction intervals at configurable quantiles, not just a central estimate
- Intermittent-demand handling with explicit zero-inflated output where that is the right model
- Decomposition into base, seasonal, promotional and price effects
- New-product forecasts from attribute-based analogues, flagged as such
- Scenario forecasts for a planned promotion or price change
- Recommended order quantity given your service-level target and lead time
- Measured accuracy per SKU group, published alongside the forecast rather than in a separate report
Endpoints
| Method | Path | Returns |
|---|---|---|
| POST | /v1/forecast | Forecast a set of SKU and location pairs over a horizon |
| POST | /v1/forecast/scenario | Forecast under a planned price change or promotion |
| GET | /v1/forecast/{job_id} | Retrieve a completed batch forecast job |
| POST | /v1/replenishment/suggest | Order quantities from the forecast, lead time and service target |
| GET | /v1/accuracy | Realised accuracy by SKU group, location and horizon |
| POST | /v1/history/ingest | Push sales, stock and promotional history |
Request and response
illustrativeRequest
{
"horizon": { "periods": 8, "granularity": "week" },
"items": [
{ "sku": "KT-4480-BLK", "location": "store_204" },
{ "sku": "KT-4480-BLK", "location": "dc_north" }
],
"quantiles": [0.5, 0.9, 0.95],
"include": ["decomposition", "replenishment"],
"service_level": 0.95
}Response
{
"generated_at": "2026-10-22T02:10:00Z",
"model_version": "wk2026-41",
"forecasts": [
{
"sku": "KT-4480-BLK",
"location": "store_204",
"regime": "intermittent",
"periods": [
{ "week": "2026-W44", "q50": 3, "q90": 7, "q95": 9, "p_zero": 0.21 },
{ "week": "2026-W45", "q50": 4, "q90": 9, "q95": 11, "p_zero": 0.18 },
{ "week": "2026-W46", "q50": 6, "q90": 13, "q95": 16, "p_zero": 0.11 }
],
"decomposition": { "base": 3.4, "seasonal": 1.1, "promotional": 0.0, "price": -0.3 },
"replenishment": { "order_qty": 24, "cover_weeks": 4, "lead_time_days": 11 },
"accuracy": { "group": "small_appliances_store", "wape_8wk": 0.31 }
}
],
"warnings": [
{ "sku": "KT-4480-BLK", "location": "dc_north",
"warning": "history_shorter_than_52_weeks", "effect": "wider_intervals" }
]
}Where the data comes from
| Your sales history | Transaction or daily sales by SKU and location — the single most important input, and the one whose depth sets the ceiling on accuracy |
| Stock and availability history | Without it, a week of zero sales caused by a stockout is learned as low demand, which poisons the model |
| Promotional and price history | Past mechanics, dates and price points, so promotional lift is attributed rather than absorbed into the baseline |
| Product attributes and hierarchy | Category, brand and attribute data, which is how a new SKU inherits a forecast from comparable lines |
| Calendar and event data | Holidays, school terms, local events and trading-day effects by location |
| Weather history and forecast | Licensed where needed; genuinely predictive for a narrow set of categories and close to noise for the rest |
The intelligence layer
The difference between a demo and a service is mostly in this section. These are the parts that keep the answer trustworthy once real traffic is hitting it.
- Hierarchical forecasting with reconciliation, so store, region and national forecasts sum consistently instead of contradicting each other
- Separate model families for fast-moving, slow-moving and intermittent series, selected per series by validated performance rather than by one global choice
- Censored-demand correction that treats stockout periods as a lower bound on demand rather than as observed demand
- Quantile estimation directly, instead of fitting a mean and bolting on a normality assumption that intermittent series violate
- Promotional lift modelled with cannibalisation and pull-forward effects on related SKUs
- Cold-start forecasting from attribute-based nearest neighbours, returned with an explicit low-confidence marker
- Rolling-origin backtesting across multiple horizons, reported as WAPE and quantile loss, never as an in-sample fit
- Production monitoring on forecast bias by SKU group, because drift shows up as persistent bias long before accuracy collapses
What it changes for the business
Fewer stockouts
Service-level targets become something you set and measure rather than approximate with a safety multiplier.
Less markdown
Over-ordering on seasonal lines falls when the upper quantile is honest about the downside.
Planner leverage
Buyers spend their time on exceptions and judgement calls instead of rebuilding spreadsheets each week.
Working capital
Holding cover where it is justified and cutting it where it is not releases cash tied up in slow stock.
How it fits into your product
How it embeds
- Batch endpoint with job polling for the weekly or nightly planning run, sized for millions of SKU-location pairs
- Synchronous scenario endpoint so a buyer can test a promotion while they are planning it
- Direct write-back of suggested order quantities into your ERP or replenishment system
- Flat-file and SFTP ingestion where your history lives in a warehouse rather than an API
- Accuracy endpoints your planning team can audit, so the model is accountable rather than trusted
- Deployment inside your own data platform where sales history cannot be exported
Included in every build
- Authentication, scoped API keys and per-customer rate limiting
- Input validation with predictable, documented error responses
- Versioned endpoints so your integration never breaks without notice
- Request and response logging for audit and dispute resolution
- Latency, error-rate and usage monitoring with alerting
- OpenAPI specification, sandbox environment and client examples
- Backups, failover design and a documented recovery procedure
- An agreed support arrangement once the service is live
How we would build it
about 20 weeksDiscovery and feasibility
Weeks 1–3
This one depends heavily on data access, so we start by proving the sources exist, can be licensed for your use, and actually carry the signal the model needs. If they do not, you find out here.
Architecture and baseline model
Weeks 4–6
A written architecture and a baseline model measured against a holdout period, so you know what accuracy you are buying before the full build starts.
Production build
Weeks 7–16
Data pipelines, model training and serving, historical archive, validation harness, API, security, monitoring and documentation.
Validation and integration
Weeks 17–20
Backtesting against held-out history, accuracy reporting your team can audit, integration support and an agreed retraining cadence.
Commercial models
There is no fixed price list, because the cost is driven by data complexity, integration count, model requirements, request volume and the support level you need. Scope is agreed in writing before development starts.
Fixed-scope prototype
A defined slice of the service, built and priced as one piece of work. The usual first step when the business case needs proving internally.
Fixed-price build
An agreed scope against a written architecture, delivered for an agreed price. Best when the requirements are already clear.
Build then retainer
We build the service, then operate and improve it under a monthly agreement covering monitoring, updates and model maintenance.
White-label product
The service runs under your brand, your domain and your pricing, with MLPivot invisible to your customers.
Questions buyers ask
How much history do you need?
Two full years is comfortable, one year is workable, and anything less means the seasonal component is largely guessed. The API does not refuse to forecast short series — it widens the intervals and attaches a warning, which is more useful than a confident number built on nine weeks of data.
Will this beat our current method?
On the long tail and on promoted lines, very likely. On high-volume stable SKUs your existing method may already be close to the achievable limit, and we would tell you that rather than claim a uniform improvement. The prototype measures both on the same holdout period so the comparison is yours, not ours.
What about products with no history at all?
They are forecast from attribute-based analogues and marked as cold-start with wide intervals. It is the weakest part of any demand system and we would not dress it up. For a genuinely novel product category, a planner's judgement will beat the model for the first season.
Can it forecast demand we never observed?
No, and this is the limitation buyers most often miss. If an item was out of stock for six weeks, the model can correct for censoring but it cannot know how much you would have sold. We estimate it with an uncertainty range and label it as an estimate.
How often does it retrain?
Weekly is typical for retail, with daily inference. Retraining cadence is a decision we make with you based on how fast your assortment and demand patterns move, and it is written into the support arrangement rather than left implicit.
Related blueprints
Promotion Optimisation API
Measured promotion effectiveness and margin-aware discount recommendations, so a promotional calendar is built on what actually worked.
Return Probability API
Predicted return likelihood and probable reason for an order line, scored before dispatch so you can intervene while it still matters.
Competitor Price Monitoring API
Competitor prices, discounts and stock status for your catalogue, delivered as a change feed your pricing tools can act on.
Want this built for your platform?
Tell us what your product does today and what you want another system to be able to ask it. We will come back with an approach, a scope and a price.