Integration Tasks

Every batch you load or delete creates an integration task, which tracks the batch from the moment GAINS Connect accepts it until GAINS has finished loading it. This page explains task statuses, and how to read, follow, list and cancel tasks.

Task statuses

`Status`	Meaning	Final
`Received`	Accepted. No GAINS load for this data is scheduled yet.	No
`Queued`	Accepted and waiting for the next scheduled GAINS load. `StatusMessage` gives the expected processing time.	No
`PendingReview`	A SKU-location delete held until you approve or reject it. Nothing has been deleted.	No
`Processing`	GAINS is loading the records.	No
`Completed`	Loading finished and at least one record was loaded. `Batch` gives the counts and lists any record GAINS refused.	Yes
`RejectedFailedProcessing`	Loading finished but GAINS refused every record. `Batch.RejectedRecords` says why.	Yes
`RejectedNotApproved`	You rejected a SKU-location delete under review. Nothing was deleted.	Yes
`Cancelled`	You or GAINS cancelled the task before it was processed. Nothing was loaded.	Yes
`Failed`	The load stopped on an unexpected error. Send the batch again, and contact your GAINS representative if it fails again.	Yes

Reading a task

Call GET /tasks/{TaskId} with the TaskId from the submit response:

{
  "TaskId": "c2791b62-508f-4aaa-b011-3764ff4625ee",
  "TaskType": "InboundLocation",
  "Status": "Queued",
  "StatusMessage": "Expected processing time is 2026-05-22 02:00:00.",
  "Batch": {
    "TotalRecords": 2,
    "Accepted": null,
    "AcceptedWithExclusions": null,
    "Rejected": null,
    "RejectedRecords": []
  },
  "StatusUpdatedOn": "2026-05-21 16:12:08",
  "CreatedOn": "2026-05-21 16:12:08",
  "CreatedBy": "[email protected]",
  "UpdatedBy": null,
  "Comments": null,
  "UpdatedOn": null
}

How to read the counts in Batch:

TotalRecords counts the records in the task. Records rejected at submit are not part of the task and are not counted.
Accepted, AcceptedWithExclusions and Rejected are null until the task is Completed or RejectedFailedProcessing, and RejectedRecords stays empty until then; see Rejections while loading.
A delete task has no AcceptedWithExclusions: its Batch gives Accepted and Rejected only.

UpdatedBy, UpdatedOn and Comments record a review decision; see SKU-location delete review. Times are GAINS Connect server time, in the form YYYY-MM-DD HH:MM:SS. The API Reference describes every field.

A TaskId that GAINS Connect does not hold, including one older than the retention period below, answers 400 That task does not exist.

Following a task

You can follow tasks in two ways:

Polling. Call GET /tasks/{TaskId} until Status is final. A task does not move until the GAINS load runs, so while it is Queued, use the expected processing time in StatusMessage to decide when to check again. To follow many tasks, list them (see Listing tasks) instead of reading each one.
Webhook. Enable the TaskStatusUpdate trigger. Each time a task's status changes you receive a delivery whose Data list holds the task, in the same form as above; one delivery can carry several tasks. Add a filter such as Status IN ('Completed', 'RejectedFailedProcessing', 'RejectedNotApproved', 'Cancelled', 'Failed') to receive final statuses only. See Webhooks and Webhook Filters.

Use the webhook when you follow many tasks or need to act as soon as a load finishes; poll when you cannot receive webhooks. Both show the same task.

How long tasks are kept

Tasks are kept for 30 days after they are created, then removed with their records and rejections. Store the TaskId and anything you need from the task, such as Batch.RejectedRecords, in your own system before then.

Listing tasks

GET /tasks returns tasks oldest first, in pages, under Data, as described in Pagination. Filter by status, task type and creation time; the API Reference lists the parameters.

GET /api/v1/tasks?Status=RejectedFailedProcessing,Failed&DateStart=2026-05-21%2000:00:00 HTTP/1.1
Host: acme.gainsystems.com
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

Task types

Each task has a TaskType naming the kind of data it carries, for example InboundLocation or DeleteSku. Use it to filter GET /tasks and TaskStatusUpdate webhooks. The task type of every inbound endpoint is listed in Inbound Subjects; POST /supply-transactions/link-order is the one inbound endpoint that creates no task.

Cancelling a task

POST /tasks/{TaskId}/cancel withdraws a task that GAINS has not started loading: one in Received, Queued or PendingReview. Once a task is Processing it can no longer be cancelled, and the request answers 400.

{
  "CancelledOn": "2026-05-21 16:20:44",
  "Status": "Cancelled"
}

Loading Data: sending a batch and the responses a submit returns.
Inbound Subjects: the TaskType of each endpoint.
Rejected Records: reading and correcting rejected records.
Deleting Data: delete tasks and the SKU-location review.
Webhooks: the TaskStatusUpdate trigger.