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 submit 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 submits 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 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": "ASM-7701",
    "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
          }
        ],
        "ExtendedData": {
          "ContractReference": "ACME-2026-114"
        }
      },
      {
        "LocationCode": "DAL02",
        "StandardCost": 9.6,
        "CapacityUnits": 800.0,
        "Weight": 40,
        "PriceBreaks": [
          {
            "Break": 1,
            "MinOrderQty": 200,
            "UnitCost": 9.6
          }
        ]
      }
    ]
  }
]

ExtendedData on the first location is optional: send it only for attributes the customer has configured for you.

Fields

One record is an item and one of your supplier codes, with an entry in Locations for each customer location you supply it to. Each location carries your unit cost, your production capacity, your share of the volume when the customer splits it between alternative suppliers, and your quantity price breaks. The API Reference for POST /partners/vendor-parameters lists every field, which are required, and the values each accepts.

Locations[].ExtendedData carries additional attributes the customer has configured for you to send. Ask the customer's GAINS representative which ones apply; see Sending Extended Data.

Rules

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.
Send an Idempotency-Key so that a resend after a lost response is not loaded twice. Which key to resend with depends on the response you received; see Idempotency.

Responses

A partner submit answers like any other submit: 202, 207 or 422 with a TaskId and any rejected records, as described in Submit responses. The valid records are then loaded in the background as a task; follow it as described in Integration Tasks.

These responses are specific to partners:

Status	Meaning
`400 Bad Request`	A `SupplierCode` is not mapped to you, or your token does not identify a partner. The whole request is refused; `Reason` explains which.
`401 Unauthorized`	Basic credentials were sent. Partner APIs accept Bearer tokens only.
`403 Forbidden`	Your token does not grant access to partner vendor parameters, or the partner service is not enabled in the customer's environment.

Every other status, such as 426 and 429, means what it means on any endpoint; see Errors & Retries.

Authentication: request a Bearer token
Loading Data: how a submit is accepted and the responses it returns
Integration Tasks: follow the task a submit creates
Idempotency: resend safely
Sourcing & Product Structure: vendor data the customer loads
Errors & Retries