Getting Started with GAINSConnect

GAINS is a supply chain planning platform covering demand planning, inventory optimization and replenishment. GAINS Connect is its REST API for exchanging planning data with your systems. You load master and transactional data into GAINS, read planning results back, and receive webhooks when results change.

GAINS also supports file-based integration. This documentation covers the API only. Read this page first, then follow the links to the guide for each topic.

What GAINS Connect exchanges

Your ERP or other system of record pushes the data GAINS plans from, and pulls back the results: replenishment orders and the planning parameters GAINS optimizes.

Typical data exchanged between an ERP system and GAINS

The diagram shows a typical integration. The endpoints available to you are listed in the API Reference, and your GAINS representative confirms which ones your project uses.

Before you start

Your GAINS representative gives you two things:

You need	Details
Your environment's address	`https://{env}.gainsystems.com`, where `{env}` is your environment. An on-premise installation uses its own host.
Credentials	A GAINS user name and password, or a client ID and secret for OAuth 2.0. See Authentication.

Every endpoint path starts with /api/v1. Requests and responses are JSON: send Content-Type: application/json with every request that has a body. Field names are PascalCase, for example ItemCode and TaskId; see Data Formats & Conventions.

Check your connection

Call GET /ping to confirm you can reach your environment. It needs no credentials, and ignores any you send.

GET /api/v1/ping HTTP/1.1
Host: acme.gainsystems.com

{
  "Status": "success",
  "Version": "2026.10.1-968d6eb9",
  "Config": {
    "InboundEndpoints": true,
    "Webhook": "v2",
    "Mail": true
  },
  "Services": {
    "GAINSX": {
      "Version": "10.0-ER2610",
      "Status": "success"
    },
    "LTP": {
      "Version": "cloud",
      "Status": "not-configured"
    },
    "SOA": {
      "Version": "cloud",
      "Status": "not-configured"
    }
  }
}

Field	What it tells you
`Version`	The GAINS Connect release your environment runs.
`Config.InboundEndpoints`	`true` when your environment accepts data loads; `false` when loads are not enabled or GAINS cannot be reached.
`Services.GAINSX.Status`	`success` when GAINS Connect can reach GAINS, `failed` when it cannot.
`Services.GAINSX.Version`	The GAINS version installed. Some endpoints need a minimum version; their reference page states it.

Which endpoints need a newer GAINS version, and what the API answers when GAINS is unavailable, is described in GAINS Version Requirements & Availability.

Authenticate

Every endpoint except GET /ping needs credentials. GAINS Connect accepts Basic authentication with a GAINS user, or a Bearer token issued by the GAINS authorization server. See Authentication.

How data moves

Direction	How it works	Start with
Inbound: you send data to GAINS	`POST` a JSON array of records. GAINS Connect validates it, answers at once with a task, and loads the data in the background.	Inbound Endpoints & Integration Tasks
Outbound: you read data from GAINS	`GET` an endpoint. Results come back one page at a time.	Outbound Overview: Pull or Push
Webhooks: GAINS sends data to you	You register a URL. GAINS Connect posts changes in GAINS to it, grouped according to your delivery settings.	Webhooks

Send data

Each load endpoint accepts up to 1000 records per request.

POST /api/v1/skus HTTP/1.1
Host: acme.gainsystems.com
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJqTl9F...
Content-Type: application/json
Idempotency-Key: 6f1c2a4e-8d3b-4f5a-9b7e-2c1d0e9f8a76

[
  {
    "ItemCode": "ASM-7701",
    "Description": "Hydraulic pump assembly",
    "Department": "HYD",
    "Group": "PUMPS"
  }
]

{
  "Status": "Received",
  "TaskId": "c81936e3-e41c-455a-bb9c-055e3c1b395c"
}

A 202 means every record passed validation. A 207 or 422 lists rejected records; see Submit responses.

Use the TaskId with GET /tasks/{TaskId} to follow the load until it reaches a final status, such as Completed, Failed or Cancelled. To retry a load safely, send an Idempotency-Key; see Idempotency.

Read data

Outbound endpoints return a Data array and a Paging block. Pass Paging.NextCursor back as the Cursor query parameter to fetch the next page. See Pagination. Which endpoint to read, and when to use a webhook instead, is in Outbound Overview: Pull or Push.

Guides

The API Reference describes every endpoint, field and response. The Changelog lists what changed in each release. The guides below explain how to use them.

Basics

Guide	Read it to
Authentication	Get credentials and call the API with them.
Data Formats & Conventions	Name fields, send values of the right type, and write dates and times.
Errors Handling & Exceptions	Read an error response and decide whether to retry.
GAINS Version Requirements & Availability	Check which endpoints need a newer GAINS X, and what to do when GAINS is in maintenance or unavailable.
Idempotency	Retry a load without loading it twice.

Webhooks

Guide	Read it to
Webhooks	See the triggers and where to start.
Configuring Webhooks	Create and manage webhook configurations.
Webhook Filters	Send only the records you want.
Delivery & Recovery	Follow deliveries, retries, resends and the queue.
Receiving Webhooks	Build the endpoint that receives deliveries, answer them and troubleshoot failures.
OAuth 2.0 Webhook Destinations	Authenticate deliveries with an OAuth 2.0 token.
Webhook Payload Samples	See what each trigger sends.

Inbound

Guide	Read it to
Inbound Endpoints & Integration Tasks	Load data and track the task.
Inbound Data Model	Find the fields that identify each record, the required fields and the rules per subject.
Rejected Records	Find out why records were rejected.
Load Throughput & Retries	Size batches, handle a `429` and retry loads safely.
Deleting Data & SKU-Location Review	Delete records and follow the review of SKU-location deletes.
Extended Data - Inbound	Send attributes of your own with inbound records.
Custom Schema	Load and read data through a custom schema set up by GAINS.

Outbound

Guide	Read it to
Outbound Overview: Pull or Push	Choose an outbound endpoint, a webhook, or both.
Pagination	Page through outbound results.
Replenishment Orders	Retrieve submitted purchase, transfer, work and production orders.
Forecasts	Retrieve forecasts.
Inventory Policies	Retrieve inventory policies and service levels.
Extended Data - Outbound	Receive and filter by extended data.

Partners

Guide	Read it to
Introduction to Partner APIs	Load data as a partner on a customer's behalf.

Get help

For credentials, environment addresses and configuration, contact your GAINS representative.
When a request answers 500 with an error_id, send that ID to [email protected]. It lets support find the failure.