Outbound Overview: Pull or Push

GAINS Connect gives you two ways to take data out of GAINS: you read it from an endpoint when you choose (pull), or GAINS sends it to your URL by webhook when something happens (push). This page lists every outbound endpoint, says which subjects you can also receive by webhook, and helps you decide which to use. It also covers demand history, order requisitions and master data, which have no guide of their own.

Pull or push

When to read an endpoint

• You need the full current state, for example a first load, or a nightly copy of every inventory policy.
• You want to reconcile what you hold against what GAINS holds.
• The subject has no webhook: demand history, requisitions, service levels, the aggregate forecast, bills of material, supercessions, master data and lead-time prediction.

An endpoint does not track changes. None of them can return only the records that changed since a given time, and none remembers what you have already read: each call returns everything that matches your filters. The date filters that exist select on business dates, not on when a record changed.

When to use a webhook

• You want to act on events as they happen: a submitted order, a changed policy or forecast.
• You want only what changed. The policy and forecast triggers send a SKU-location only when GAINS detects that it has changed.
• You want to route data. A trigger filter, for example ReceivingLocation IN ('CHI01', 'DAL02'), sends each destination only the records it needs.

See Webhooks for setting up destinations, filters, retries and resending.

Using both

Where a subject has a webhook, use both channels together:

1. Load once from the endpoint. Read every page of the subject to start from the full current state.
2. Keep up to date from the webhook. Process each delivery as it arrives. Deliveries can repeat, so make processing a record twice harmless: key orders on TrackingNumber, and policies and forecasts on ItemCode and LocationCode.
3. Reconcile on a schedule. Read the endpoint again, for example daily, and compare. This catches anything a delivery missed, such as a payload dropped after its last retry. For orders, you can also re-read a single order with TrackingNumber.

Outbound endpoints

Every endpoint below returns DataType, Data and Paging, and takes Size and Cursor; see Pagination. A webhook delivery carries the same DataType and Data, without Paging. Filters that take a list accept up to 10 comma-separated values, and different filters combine with AND.

Replenishment orders and requisitions

See Replenishment Orders for the order endpoints, and Order requisitions below.

Demand planning

See Forecasts, and Demand history below.

Inventory optimization

See Inventory Policies for policies and service levels, and Master data below for bills of material and supercessions.

Locations, vendors and customers

Lead-time prediction

These endpoints are available only when lead-time prediction is enabled for your GAINS instance. Every request names a model run with ModelRunDate.

None of them has a webhook or extended data.

Your own custom data

GET /custom/{ApiRoute} reads back the records loaded through POST /custom/{ApiRoute}, for a route your GAINS representative has set up.

Demand history

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

This request reads the September demand shipped from CHI01:

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": null,
      "IdealShipLocationCode": "CHI01",
      "ActualShipLocationCode": "CHI01",
      "Department": "10",
      "Group": "220",
      "InventoryClass": "A",
      "UnitOfMeasure": "EA",
      "OrderNumber": "SO-2026-118734",
      "LineNumber": "1",
      "CustomerCode": "C10045",
      "CustomerShipToCode": "C10045-02",
      "ExclusionFlag": false,
      "RequestDate": "2026-09-14 00:00:00",
      "PromiseDate": "2026-09-16 00:00:00",
      "ShipDate": "2026-09-16 00:00:00",
      "RequestQuantity": 24,
      "OrderPrice": 89.5,
      "LineComment": null,
      "Status": "03",
      "DemandType": 0
    }
  ],
  "Paging": {
    "NextCursor": null,
    "CurrentDataCount": 1
  }
}

Demand history filters

• Dates include a time, as in the example above; see Dates in query parameters.
• RequestDateEnd is exclusive. To read September, end at 2026-10-01 00:00:00.
• exclude leaves out every match of either list. ItemLocationFilterType=exclude&ItemCode=ASM-7701&LocationCode=DAL02 leaves out item ASM-7701 everywhere, and every item shipped from DAL02.

You can also filter on extended data attributes that your GAINS representative has made available as filters.

Reading demand history regularly

Size counts order lines. The date filters select on the date a line was requested, not on when GAINS received it, so a line loaded late for an earlier date appears in a window you may already have read. To keep a copy current, re-read a recent window, for example the last 60 days, and replace what you hold for it.

Order requisitions

A requisition is a single order recommendation in GAINS: one item to be ordered from one shipping location into one receiving location, with its quantity, dates and cost. Buyers review requisitions and submit them as orders. A submitted order groups lines under a TrackingNumber and is read from the order endpoints; GET /replenishment/requisitions returns the recommendations line by line.

This request reads the purchase requisitions for CHI01:

GET /api/v1/replenishment/requisitions?OrderType=purchase_order&ReceivingLocation=CHI01

{
  "DataType": "requisition",
  "Data": [
    {
      "OrderType": "purchase_order",
      "ItemCode": "ASM-7701",
      "ItemDescription": "Hub assembly, front",
      "ShippingLocation": "ACME",
      "ReceivingLocation": "CHI01",
      "ReceiveDate": "2026-11-23",
      "ReleaseDate": "2026-10-26",
      "DeliveryDate": "2026-11-21",
      "ApprovalCode": "U",
      "Quantity": 480,
      "Cost": 62.1,
      "LineComment": null,
      "OrderNumber": null,
      "BuyerCode": "JSMITH",
      "PreOrderCarryCost": 112.4,
      "DaysOverLeadTime": 0.0,
      "Weight": 6.2,
      "Volume": 0.05,
      "ConversionFactor": 12.0,
      "BundleCode": 3,
      "Department": "10",
      "Group": "220"
    }
  ],
  "Paging": {
    "NextCursor": null,
    "CurrentDataCount": 1
  }
}

Requisition filters

• OrderType takes one value, spelled as OrderType is returned. Without it, every type is returned.
• The default approval codes differ from the order endpoints. Without ApprovalCode, requisitions with codes U, P and Q are returned, and approved (A) lines are not. Name every code you want, for example ApprovalCode=A,U.

Submitted or not

The endpoint filters on approval code only. It does not look at whether a line has been submitted, and a requisition carries no TrackingNumber, so you cannot tell from the response whether a line is already part of an order. To process submitted orders, use the order endpoints or their webhooks instead.

Size counts requisition lines. Requisitions have no webhook.

Master data

The master data endpoints return the records as GAINS holds them at the time of the call, ordered by their codes.

• Bills of material include every component GAINS holds, whatever its EffectiveFrom and EffectiveTo dates. Check those dates to find the components in effect.
• Supercession dates both filter on the effective date of the relationship: EffectiveDateStart is inclusive, EffectiveDateEnd exclusive; see Dates in query parameters.

Errors

Access is granted per group: replenishment (orders and requisitions), demand planning (forecasts and demand history), inventory optimization (policies, service levels, bills of material and supercessions), master data (locations, vendors and customers), lead-time prediction, and custom data. Ask your GAINS representative to change what your client can read. See Errors Handling & Exceptions for the error response body.

Related

• Webhooks
• Pagination
• Replenishment Orders
• Forecasts
• Inventory Policies
• Extended Data - Outbound