Forecasts

GAINS Connect gives you the demand forecast GAINS calculates for each SKU-location, in weekly or monthly buckets. This page explains which endpoint to call, what a forecast record contains, and how to receive changed forecasts by webhook.

Forecast endpoints

All three return the same structure, with DataType forecast. 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: what you receive is the forecast as it stands in GAINS at the time of the call. Size counts SKU-locations; see Pagination.

What a forecast contains

Each record is one item, with one entry in Locations per SKU-location, holding one bucket per forecast period.

Compare the two quantities to see where a planner has adjusted the forecast.

Parameters

• ItemCode, LocationCode and StockIndicator take a comma-separated list of up to 10 values: LocationCode=CHI01,DAL02.
• Different parameters combine with AND.
• Period counts buckets, not dates. Period=6 on the weekly endpoint returns six weekly buckets, starting from bucket 1.

You can also filter on extended data attributes that your GAINS representative has made available as filters. See Extended Data - Outbound.

Receiving changed forecasts by webhook

Rather than reading every forecast on a schedule, you can have GAINS send you the forecasts that change:

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. There is no webhook for the aggregate forecast.

Both triggers share the DataType forecast. If you subscribe to both, send them to different destinations, or tell them apart by the length of their buckets.

Like the other triggers, a forecast trigger can take a filter, for example LocationCode IN ('CHI01', 'DAL02'), so that GAINS sends only the forecasts you need. See Webhooks for setting up destinations and filters, and Webhook Payload Samples for sample payloads.

A common pattern is to read the full forecast once from the endpoint, then keep it up to date from the webhook.

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 Extended Data - Outbound.

Errors

See Errors Handling & Exceptions for the error response body.

Related

• To load forecasts produced in another system into GAINS, use POST /forecasts.
• Outbound Overview: Pull or Push
• Webhooks
• Pagination
• Extended Data - Outbound