Introduction to Partner APIs

Partner APIs let a supplier of a GAINS customer maintain its own data in that customer's GAINS environment, instead of sending it to the customer to load. This page is for partners: it explains how a partner gets access, what it can update, and how to send vendor parameters.

What a partner is

A partner is a supplier that a GAINS customer has authorized to update data about the items it supplies. The customer decides which of its supplier codes the partner may act for, and GAINS sets up the partner's access in that customer's environment.

A partner can update only records for the supplier codes the customer has mapped to it. Partner APIs accept data only; they return none of the customer's data.

Getting access

The customer authorizes you. The GAINS customer asks their GAINS representative to register you as a partner and to map the supplier codes you will maintain.
GAINS issues your credentials. You receive an OAuth 2.0 client ID and secret identifying you as that partner.
You request a token and call the API. Request an access token as described in Authentication, and send it on every call as Authorization: Bearer <token>. Request a new token when the current one expires.

Partner APIs accept bearer tokens only; Basic authentication is refused with 401 and This endpoint accepts Bearer tokens only.

Vendor parameters

POST /partners/vendor-parameters loads the cost, capacity, allocation weight and price breaks you offer for an item at each of the customer's locations.

Its reference page states the minimum GAINS X version it needs in the customer's environment; on an earlier version it answers 426.

POST /api/v1/partners/vendor-parameters
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJqTl9F...
Content-Type: application/json
Idempotency-Key: 7c9e6679-7425-40de-944b-e07fc1f90ae7

[
  {
    "ItemCode": "938939",
    "SupplierCode": "ACME",
    "Locations": [
      {
        "LocationCode": "CHI01",
        "StandardCost": 9.85,
        "CapacityUnits": 1200.0,
        "Weight": 60,
        "PriceBreaks": [
          {
            "Break": 1,
            "MinOrderQty": 100,
            "UnitCost": 9.85
          },
          {
            "Break": 2,
            "MinOrderQty": 500,
            "UnitCost": 9.4
          },
          {
            "Break": 3,
            "MinOrderQty": 1000,
            "UnitCost": 8.95
          }
        ],
        "ExtendedData": {                    // optional - only if configured
          "ContractReference": "ACME-2026-114"
        }
      },
      {
        "LocationCode": "DC-EAST",
        "StandardCost": 9.6,
        "CapacityUnits": 800.0,
        "Weight": 40,
        "PriceBreaks": [
          {
            "Break": 1,
            "MinOrderQty": 200,
            "UnitCost": 9.6
          }
        ]
      }
    ]
  }
]

Fields

Field	Type	Rules
`ItemCode`	string	Required. The customer's item code, 1 to 65 characters.
`SupplierCode`	string	Required. The customer's code for you as a supplier, 1 to 80 characters. Must be one mapped to you.
`Locations`	array	Required, at least one entry.
`Locations[].LocationCode`	string	The customer's location code, up to 80 characters.
`Locations[].StandardCost`	number	Your unit cost.
`Locations[].CapacityUnits`	number	Your production rate, in units.
`Locations[].Weight`	integer	Your share when the customer splits volume between alternative suppliers of the item.
`Locations[].PriceBreaks`	array	Up to 3 quantity price breaks.
`PriceBreaks[].Break`	integer	Required. `1` to `3`, counting up from the smallest quantity.
`PriceBreaks[].MinOrderQty`	integer	Required. The smallest order quantity that earns this price.
`PriceBreaks[].UnitCost`	number	Required. The unit cost at this break.
`Locations[].ExtendedData`	object	Additional attributes the customer has configured for you to send. Ask the customer's GAINS representative which ones apply.

Price breaks must be numbered from 1 without gaps or repeats: 1, 1, 2 or 1, 2, 3.

Rules

Send up to 1000 records per request, a record being one item and supplier with its locations.
Every SupplierCode must be mapped to you. GAINS Connect checks the supplier codes of the request together: if any is not mapped to you, the whole request is refused with 400 and nothing is loaded.
Records create or update; nothing is deleted. There is no endpoint for removing vendor parameters. Ask the customer to remove them.
Retry safely with Idempotency-Key. A retried request with the same key is refused with 400 instead of being loaded twice. See Idempotency.

Responses

The request is validated record by record, and the valid records are loaded in the background as a task.

Status	Meaning
`202 Accepted`	Every record passed validation. The body has the `TaskId` and its `Status`.
`207 Multi-Status`	Some records passed and are being loaded; the others are listed in `RejectedRecords` with their reasons. See Rejected Records.
`400 Bad Request`	A supplier code is not mapped to you, or your token does not identify a partner. `Reason` explains which.
`401 Unauthorized`	No token, an expired token, or Basic credentials.
`403 Forbidden`	Your token does not grant access to partner vendor parameters.
`422 Unprocessable Content`	No record passed validation, the body is empty, or it holds more than 1000 records.
`426 Upgrade Required`	The customer's GAINS X version is too old for this endpoint.
`429 Too Many Requests`	GAINS is busy loading earlier submissions. Retry after the number of seconds in the `Retry-After` header.

{
  "Status": "Queued",
  "TaskId": "c2791b62-508f-4aaa-b011-3764ff4625ee"
}

An accepted request is loaded into GAINS in the background, and a record can still be refused at that stage. The task tracks the outcome; see Task statuses.