Forecasts & Demand History

GAINS Connect gives you the two sides of demand planning in GAINS: the forecast GAINS calculates for each SKU-location, in weekly or monthly buckets, and the demand history it forecasts from. This page explains which endpoint to call, how records are grouped, and how to receive changed forecasts by webhook.

Forecast endpoints

All three return the same structure. The aggregate endpoint returns only the SKU-locations that have an aggregate forecast in GAINS.

Reading forecasts

This request reads the next three monthly buckets for every item at CHI01:

GET /api/v1/demand-planning/forecast/monthly?LocationCode=CHI01&Period=3

{
  "DataType": "forecast",
  "Data": [
    {
      "ItemCode": "ASM-7701",
      "Locations": [
        {
          "LocationCode": "CHI01",
          "InventoryClass": "A",
          "ForecastBuckets": [
            {
              "ForecastPeriodNumber": 1,
              "ForecastPeriodStart": "2026-11-01",
              "ForecastPeriodEnd": "2026-11-30",
              "ForecastQuantityTotal": 540,
              "ForecastQuantityTotalRaw": 521
            },
            {
              "ForecastPeriodNumber": 2,
              "ForecastPeriodStart": "2026-12-01",
              "ForecastPeriodEnd": "2026-12-31",
              "ForecastQuantityTotal": 505,
              "ForecastQuantityTotalRaw": 498
            },
            {
              "ForecastPeriodNumber": 3,
              "ForecastPeriodStart": "2027-01-01",
              "ForecastPeriodEnd": "2027-01-31",
              "ForecastQuantityTotal": 470,
              "ForecastQuantityTotalRaw": 470
            }
          ]
        }
      ]
    }
  ],
  "Paging": {
    "NextCursor": null,
    "CurrentDataCount": 1
  }
}

The endpoints return the current forecast of every SKU-location that matches your filters, each time you call them. They do not keep track of what you have already read.

Each record is one item, with one entry in Locations per SKU-location, holding one bucket per forecast period. Size counts SKU-locations, not items, so an item's Locations can continue on the next page: merge records with the same ItemCode across pages. See Pagination.

To see where a planner has adjusted the forecast, compare ForecastQuantityTotal, which includes planner adjustments, with ForecastQuantityTotalRaw, the forecast GAINS calculated.

Filters

Narrow what you read by item, location or stock indicator, and choose how many buckets you receive per SKU-location with Period: it counts buckets from the first, not dates. You can also filter on extended data attributes that your GAINS representative has made available as filters; see Receiving Extended Data. The API Reference describes each parameter.

Receiving changed forecasts by webhook

The weekly and monthly forecasts each have a trigger that sends the forecasts GAINS detects have changed; the trigger names are on Webhooks. There is no webhook for the aggregate forecast. To combine a first read with webhook updates, see Pull or Push.

• A delivery has the same structure as the endpoint, without Paging. Each location also carries EventOccurredAt, the time GAINS generated the forecast, which the endpoints do not return.
• Both triggers send the DataType forecast. If you subscribe to both, send them to different destinations, or tell them apart by the length of their buckets.
• A trigger can take a filter, for example LocationCode IN ('CHI01', 'DAL02'), so that GAINS sends only the forecasts you need. See Webhook Filters and Webhook Payload Samples.

Extended data

Forecasts can carry extended data on the item and on each location. Weekly, monthly and aggregate forecasts are configured separately, and the webhooks carry the same extended data as the matching endpoint. See Receiving Extended Data.

Demand history

GET /demand-planning/demand-history returns the sales history GAINS forecasts from: one record per order line, with its customer, dates, quantity and price, and the item details GAINS holds for it. Use it to copy that history into a reporting or analytics system, or to check what GAINS holds against your ERP.

This request reads the lines shipped from CHI01 that were requested in September 2026:

GET /api/v1/demand-planning/demand-history?LocationCode=CHI01&RequestDateStart=2026-09-01%2000:00:00&RequestDateEnd=2026-10-01%2000:00:00

{
  "DataType": "demand_history",
  "Data": [
    {
      "ItemCode": "ASM-7701",
      "ItemDescription": "Hub assembly, front",
      "ItemType": "FG",
      "IdealShipLocationCode": "CHI01",
      "ActualShipLocationCode": "CHI01",
      "Department": "10",
      "Group": "HUB",
      "InventoryClass": "A",
      "UnitOfMeasure": "EA",
      "OrderNumber": "SO-100482",
      "LineNumber": "1",
      "CustomerCode": "C-10452",
      "CustomerShipToCode": "ST-01",
      "ExclusionFlag": false,
      "RequestDate": "2026-09-22 00:00:00",
      "PromiseDate": "2026-09-24 00:00:00",
      "ShipDate": "2026-09-23 00:00:00",
      "RequestQuantity": 40,
      "OrderPrice": 18.75,
      "LineComment": null,
      "Status": "03",
      "DemandType": 0
    }
  ],
  "Paging": {
    "NextCursor": null,
    "CurrentDataCount": 1
  }
}

Each record is one order line, and Size counts lines. Demand history has no webhook.

Keeping a copy current

The date filters select lines by the date they were requested, not by when GAINS received them. A line loaded late, or corrected after you read it, can therefore appear or change in a window you have already read. To keep a copy current, re-read a recent window on a schedule, for example the last 60 days, and replace what you hold for that window.

Demand history can carry extended data on each line, and can be filtered by extended data attributes that your GAINS representative has made available as filters. See Receiving Extended Data.

Errors

These endpoints return the statuses described in Errors & Retries.

Related

• Outbound Subjects
• Pull or Push
• Webhooks
• Pagination
• Receiving Extended Data
• POST /forecasts: load forecasts produced in another system into GAINS