Sending Extended Data

Send attributes of your own alongside the standard fields of an inbound record. GAINS stores them with the record they arrive on. The attributes, their API labels and where they are accepted are agreed with your GAINS representative; see Extended Data.

Sending extended data

Add an ExtendedData object to the record, holding one key per attribute:

[
  {
    "ItemCode": "ASM-7701",
    "LocationCode": "CHI01",
    "Description": "Hub assembly, front",
    "ExtendedData": {
      "Region": "Midwest",
      "CostCentre": "MTN-03"
    }
  }
]

On subjects whose records have line items, ExtendedData can be configured at the header level, at the line level, or both. Each level takes only the attributes configured for it:

[
  {
    "IdealShipFromLocationCode": "CHI01",
    "CustomerRequestDate": "2026-05-22",
    "OrderEntryDate": "2026-05-20",
    "OrderNumber": "SO-2026-11873",
    "CustomerCode": "C-10452",
    "LineItems": [
      {
        "ItemCode": "ASM-7701",
        "RequestedQuantity": 40,
        "ExtendedData": {
          "PromotionCode": "SPRING26"
        }
      }
    ],
    "ExtendedData": {
      "SalesChannel": "Web"
    }
  }
]

The rules for the ExtendedData object:

Keys are the API labels agreed with your GAINS representative, spelled exactly as agreed. Keys are case-sensitive.
Values are text, sent as JSON strings, unless an attribute was set up as numeric. A numeric attribute takes a decimal number, written with a decimal point, for example 12.0; a whole number such as 12 is refused with must be of type Double. A text value cannot be longer than the length agreed for the attribute.
Required attributes must be present on every record, and null is not accepted. When a record has no value for a required text attribute, send an empty string (""). A required numeric attribute must always carry a number.
Optional attributes may be left out.
Any other key is refused, including a correct label sent at the wrong level.

Where extended data is accepted

Which inbound subjects accept ExtendedData is listed in Inbound Subjects. On most of them it sits on each record. Where a record is nested, these are the levels it can be configured at:

Endpoint	Levels
`POST /inventory-lots`	Each lot (`Locations[].Lots[]`)
`POST /demand-transactions`, `POST /demand-transactions-splits`	Each transaction, and each of its `LineItems`
`POST /demand-events`	Each event, and each of its `Details`
`POST /supply-transactions`, `POST /supply-transactions-splits`	Each transaction, and each of its `LineItems`
`POST /vendor-alternatives`	Each vendor (`Vendors[]`)
`POST /partners/vendor-parameters`	Each location (`Locations[]`)

Error scenarios

Extended data is checked with the rest of the record when you submit it. A record whose extended data is invalid is rejected on its own, and the other records in the request are still accepted. Rejected records are reported as described in Rejected Records.

{
  "Status": "Received",
  "TaskId": "8f3c1d02-5a77-4e61-9b0e-2d41c7a9f5b3",
  "RejectedRecords": [
    {
      "Record": {
        "ItemCode": "ASM-7701",
        "LocationCode": "CHI01",
        "Department": null,
        "Group": null,
        "Description": "Hub assembly, front",
        "InventoryClass": null,
        "DistributionLevel": null,
        "SellingPrice": null,
        "StandardCost": null,
        "FOBCost": null,
        "Weight": null,
        "Volume": null,
        "OnHand": null,
        "UnshippedQty": null,
        "PLBConversionFactor": null,
        "MaxORQInWeeks": null,
        "LeadTime": null,
        "ServiceLevel": null,
        "ReceivingCost": null,
        "CarryingCost": null,
        "PriceBreakPointer": null,
        "FreightBreakPointer": null,
        "MinimumORQ": null,
        "IncrementalORQ": null,
        "StockIndicator": null,
        "CurrentSSMinROP": null,
        "CurrentOQMax": null,
        "ParentCode": null,
        "ParentAllocation": null,
        "ItemType": null,
        "ReserveStockQuantityRSQ": null,
        "RSQApplication": null,
        "Planner": null,
        "HistoryBeginDate": null,
        "ExtendedData": {
          "CostCentre": "MTN-03"
        }
      },
      "Reasons": [
        {
          "Reason": "Region is expected as part of the payload but was not provided (path: ExtendedData)",
          "RecordKey": {
            "ItemCode": "ASM-7701",
            "LocationCode": "CHI01"
          }
        }
      ]
    }
  ]
}

The reasons you can receive, where Region stands for the attribute concerned:

Situation	Reason
A required attribute is missing, or `ExtendedData` is missing altogether	`Region is expected as part of the payload but was not provided`
A key is not a label configured for this subject and level	`Your payload field Region is not configured. Please contact your GAINS representative.`
The subject has no extended data configured, but the record carries `ExtendedData`	`Your payload contains extended data attributes; these are not configured for your instance. Please contact your GAINS representative.`
A value has the wrong type, or is `null`	`Your payload field Region must be of type String`
A numeric value is sent as text or as a whole number	`Your payload field Region must be of type Double`
A text value is longer than the agreed length	`Your payload field Region must be of type String(20)`, giving the maximum length

Extended Data: what extended data is and how it is set up.
Receiving Extended Data: reading extended data back from GAINS.
Loading Data: submitting a batch and the submit responses.
Inbound Subjects: which subjects accept extended data.
Rejected Records: reading RejectedRecords and resending corrected records.
Integration Tasks: following the load of the accepted records.