Master Data & Product Structure

GAINS Connect gives you the master data GAINS plans with: your locations, vendors and customers, and the product structure behind your items, meaning bills of material and supercessions. Use these endpoints to check what GAINS holds against your ERP, or to copy it into a reporting system. This page explains how records are grouped and how to keep a copy current.

None of these subjects has a webhook. Each call returns the records as GAINS holds them at that moment.

Reading master data

This request reads two locations:

GET /api/v1/locations?LocationCode=CHI01,DAL02

{
  "DataType": "location",
  "Data": [
    {
      "LocationCode": "CHI01",
      "Name": "Chicago DC",
      "Type": "Distribution center",
      "ParentDefaultCode": "PLT01",
      "Address1": "123 Any St",
      "Address2": null,
      "City": "Chicago",
      "State": "IL",
      "Country": "US",
      "PostalCode": "60601",
      "Latitude": 41.8781,
      "Longitude": -87.6298,
      "StartDate": "2020-01-01",
      "EndDate": null,
      "Size": "Large",
      "CurrencyCode": "USD"
    },
    {
      "LocationCode": "DAL02",
      "Name": "Dallas DC",
      "Type": "Distribution center",
      "ParentDefaultCode": "PLT01",
      "Address1": "500 Commerce St",
      "Address2": null,
      "City": "Dallas",
      "State": "TX",
      "Country": "US",
      "PostalCode": "75202",
      "Latitude": 32.7767,
      "Longitude": -96.797,
      "StartDate": "2021-06-01",
      "EndDate": null,
      "Size": "Medium",
      "CurrencyCode": "USD"
    }
  ],
  "Paging": {
    "NextCursor": null,
    "CurrentDataCount": 2
  }
}

Results are ordered by their codes and paged with Cursor; see Pagination.

How records are grouped

The same code can appear in more than one record. Combine the fields below to identify a record:

Subject	Endpoint	A record is identified by
Locations	`GET /locations`	`LocationCode`
Vendors	`GET /vendors`	`VendorCode` and `ReceiveLocationCode`. A vendor that supplies several of your locations appears once for each, with the terms and lead times for that location
Customers	`GET /customers`	`CustomerCode` and `ShipToCode`. A customer with several ship-to addresses appears once for each
Bills of material	`GET /inventory/bills-of-material`	`KitItemCode`, then `KitLocationCode` in `KitLocations`
Supercessions	`GET /inventory/supercessions`	`NewItem` (`ItemCode` and `LocationCode`), with one entry in `OldItems` per supercession record

Bills of material

A bill of material is returned per kit item. KitLocations lists each location the kit is assembled at, and Components the items used to assemble it there:

{
  "KitItemCode": "ASM-7701",
  "KitLocations": [
    {
      "KitLocationCode": "PLT01",
      "Components": [
        {
          "ComponentItemCode": "HUB-100",
          "ComponentLocationCode": "PLT01",
          "ComponentQty": 1.0,
          "ComponentYield": 0.98,
          "EffectiveFrom": "2025-01-01",
          "EffectiveTo": "2027-12-31",
          "PhantomFlag": false
        }
      ]
    }
  ]
}

Every component GAINS holds is returned, whether or not it is in effect today. Use EffectiveFrom and EffectiveTo to find the components that apply on a given date.

Supercessions

Each entry in OldItems is one supercession record in GAINS, not one replaced SKU-location. An old SKU-location superseded more than once, with different effective dates, appears once per record. Use EffectiveDate to tell the entries apart, rather than assuming each old SKU-location appears once.

Paging through grouped records

Size counts kit-locations for bills of material, and entries in OldItems for supercessions, not top-level records. A kit or a superseding SKU-location can therefore continue on the next page: when the first record of a page has the same KitItemCode, or the same NewItem, as the last record of the previous page, merge the two.

Keeping a copy current

Master data has no webhook, and the endpoints cannot return only what changed. To keep a copy current, read the full set on a schedule, for example nightly, and replace what you hold. A record that is no longer returned has been removed from GAINS. See Pull or Push.

Extended data

Locations can carry extended data, and can be filtered by extended data attributes that your GAINS representative has made available as filters. Vendors, customers, bills of material and supercessions do not carry extended data. See Receiving Extended Data.

Errors

These endpoints return the statuses described in Errors & Retries. For a Bearer client, note that locations, vendors and customers need master data access, while bills of material and supercessions need inventory optimization access, the same as inventory policies.