Supply Forecast Inventory
The Supply Forecast Ingestion API receives supply forecasts from WMS forecasting systems and feeds the event-driven inventory processing pipeline. Submissions are accepted asynchronously: the API acknowledges receipt and returns a request_id, then validates and processes the payload downstream.
A 202 confirms receipt, not validity. Every rule below is applied after the response is returned. Points that fail are recorded in FourKites service logs only — no error reaches the caller, and there is no callback today. To confirm a forecast landed, read it back through the inventory projection APIs.
Validation Rules
Two groups, and the difference matters: the first discards everything you sent, the second discards only the point at fault.
Whole submission is rejected — nothing is stored:
- forecasts is missing or empty
- forecasts contains more than 500 entries
- any forecastData contains more than 500 points
- any date is not in YYYY-MM-DD format
Only the offending point or entry is rejected — everything else is stored:
- forecastData is missing or empty — that entry only
- productId or facilityId missing, or over 100 characters
- quantityUom over 10 characters
- date missing on a point
- quantity missing, or negative
- the same date appears twice in one forecastData array
Why the split. A size breach or an unreadable date is a fault in how the submission was built, so the whole submission is refused before any of it is stored. Everything else is a fault in one row, so only that row is dropped.
Neither is reported back to you. Both are recorded in FourKites service logs against the request_id.
Date format
Dates must be YYYY-MM-DD, for example 2024-08-05. Other formats — 08/05/2024, 2024-8-5, 05-Aug-2024 — are not accepted, and a single one of them discards the entire submission.
An absent date is different: that point alone is rejected and its siblings are stored normally.
Processing granularity
Daily or weekly handling is taken from your company's forecast configuration, not from the request. Dates are stored exactly as submitted; the API does not snap them to week starts or redistribute them. Where no configuration exists, forecasts are stored as daily.
curl --location 'https://api.fourkites.com/api/v1/async/forecast/supply' \
--header 'Content-Type: application/json' \
--header 'apikey: APIKEY' \
--data '{
"messageId": "FCT-SUPPLY-2024-07-30-001",
"forecasts": [
{
"productId": "WIRE-BEL-COA-001",
"facilityId": "442344",
"quantityUom": "EA",
"forecastData": [
{
"date": "2024-08-05",
"quantity": 180.0
},
{
"date": "2024-08-06",
"quantity": 150.0
},
{
"date": "2024-08-07",
"quantity": 200.0
}
],
"referenceAttributes": {
"forecastModel": "ML_TIMESERIES_V3",
"planningGroup": "WIRE_CABLE",
"seasonalityFactor": 1.2,
"dataSource": "WMS_FORECAST_ENGINE"
}
}
]
}'import http.client
import json
conn = http.client.HTTPSConnection("api-staging.fourkites.com")
payload = json.dumps({
"messageId": "FCT-SUPPLY-2024-07-30-001",
"forecasts": [
{
"productId": "WIRE-BEL-COA-001",
"facilityId": "442344",
"quantityUom": "EA",
"forecastData": [
{
"date": "2024-08-05",
"quantity": 180
},
{
"date": "2024-08-06",
"quantity": 150
},
{
"date": "2024-08-07",
"quantity": 200
}
],
"referenceAttributes": {
"forecastModel": "ML_TIMESERIES_V3",
"planningGroup": "WIRE_CABLE",
"seasonalityFactor": 1.2,
"promotionFlag": False,
"forecastAccuracy": 0.87,
"lastModelUpdate": "2024-07-25T09:00:00Z",
"dataSource": "WMS_FORECAST_ENGINE",
"supplierLeadTime": 14,
"minimumOrderQuantity": 500
}
}
]
})
headers = {
'Content-Type': 'application/json',
'apikey': 'APIKEY'
}
conn.request("POST", "/api/v1/async/forecast/supply", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))There is no 400 response for a malformed forecast on this endpoint. Body-level problems are detected downstream, after the 202 has been returned.