Forecast

Forecast API resource representing demand forecast values per product-location, capturing predicted units across forecast horizons for replenishment planning.

Overview

The Forecast resource represents demand forecast values for a product at a given location. Each record captures the predicted demand for a future period, along with the cutoff date on which the forecast was generated and the horizon it covers. Forecast records provide the forward-looking demand signal used by the inventory optimisation engine for replenishment planning.

Resource Endpoint

/api/v2/ingest/object/{prefix}FORECAST{suffix}

Supported Methods

Method	Return Type	Description
POST	Response	Ingest (create/update) Forecast records via UPSERT operation

Request Headers

Header	Required	Description
Authorization	Yes	Your Personal Access Token (PAT) from platform.peak.ai
Content-Type	Yes	Must be application/json

Properties

Primary Keys

• product_id (string) - Unique identifier for the product. Part of the composite primary key.
• location_id (string) - Unique identifier for the location. Part of the composite primary key.
• cutoff_date (date) - The date on which the forecast was generated. Part of the composite primary key.
• start_date (date) - The first date of the forecast period. Part of the composite primary key.

Attributes

Attribute	Data Type	Required	Description
product_id	string	Yes	Unique identifier for the product being forecast
location_id	string	Yes	Unique identifier for the location the forecast applies to
cutoff_date	date	Yes	The date on which the forecast was generated, in YYYY-MM-DD format
start_date	date	Yes	The first date of the forecast period, in YYYY-MM-DD format
end_date	date	Yes	The last date of the forecast period, in YYYY-MM-DD format
horizon	integer	Yes	Number of periods ahead of the cutoff date that this forecast covers
yhat	float	Yes	Forecasted demand value for the period
frequency	integer	Yes	Length of the forecast period, in days

Relationships

Outbound References

The forecast resource does not reference any downstream resources as foreign keys.

Inbound References

The following resources are referenced by forecast:

• products — product_id → products.product_id
• locations — location_id → locations.location_id

JSON Representation

{
  "solutionName": "INV_OOTB",
  "data": [
    {
      "product_id": "PROD-001",
      "location_id": "LOC-001",
      "cutoff_date": "2025-01-15",
      "start_date": "2025-01-16",
      "end_date": "2025-01-22",
      "horizon": 1,
      "yhat": 320.5,
      "frequency": 7
    }
  ],
  "operationType": "UPSERT"
}

Example Request

curl -X POST \
  'https://ingestion.peak.ai/api/v2/objects/INV_FORECAST_OOTB' \
  -H 'Authorization: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "solutionName": "INV_OOTB",
    "data": [
      {
        "product_id": "PROD-001",
        "location_id": "LOC-001",
        "cutoff_date": "2025-01-15",
        "start_date": "2025-01-16",
        "end_date": "2025-01-22",
        "horizon": 1,
        "yhat": 320.5,
        "frequency": 7
      }
    ],
    "operationType": "UPSERT"
  }'

Important Notes

• product_id, location_id, cutoff_date, and start_date together form the composite primary key. All four fields must be provided on every record.
• All date fields must be in YYYY-MM-DD format.
• cutoff_date records when the forecast was produced; start_date and end_date bound the period the forecast value applies to.
• product_id must correspond to an existing record in the Products resource.
• location_id must correspond to an existing record in the Locations resource.
• Records are ingested via UPSERT: an existing record with matching primary keys will be updated; otherwise a new record is inserted.

Related Resources

• Products
• Locations
• Sales
• Order Parameters