Deleting Data & SKU-Location Review

This page lists every delete endpoint, the key each one takes, and how you approve or reject a SKU-location delete before anything is removed. Read it before you remove data from GAINS through the API. How tasks work in general is described in Inbound Endpoints & Integration Tasks.

Delete endpoints

Each delete takes an array of record keys, not whole records, and creates a task like a load does. GAINS removes the matching records at its next scheduled load for that kind of data.

Endpoint	Deletes	Key: required	Key: optional
`POST /skus/delete`	Items	`ItemCode`
`POST /locations/delete`	Locations	`LocationCode`
`POST /skus-locations/delete`	SKU-locations, after review	`ItemCode`, `LocationCode`
`POST /customers/delete`	Customer ship-tos	`CustomerCode`, `ShipToCode`
`POST /vendors/delete`	Vendors	`VendorCode`	`ReceiveLocationCode`
`POST /vendor-alternatives/delete`	Alternative vendors of a SKU-location	`ItemCode`, `LocationCode`, `ProductionLine`, `CapacityAllocGroup`
`POST /bills-of-material/delete`	Kit components	`KitItemCode`, `KitLocationCode`, `ComponentItemCode`, `ComponentLocationCode`, `EffectiveFrom`
`POST /supercessions/delete`	One old-to-new replacement	`NewItem` and `OldItem`, each with `ItemCode` and `LocationCode`
`POST /price-breaks/delete`	Price breaks of a SKU-location	`ItemCode`, `LocationCode`
`POST /demand-transactions/delete`	Demand transactions	`OrderNumber`, `IdealShipFromLocationCode`, `CustomerRequestDate`	`LineNumber`, `ItemCode`, `CustomerShipToCode`
`POST /demand-events/delete`	Demand events	`EventId`
`POST /supply-transactions/delete`	Supply order lines	`OrderNumber`, `LineNumber`	`SplitNumber`
`POST /usage-transactions/delete`	Usage transactions	`WorkOrderNumber`, `ActualLocationCode`, `OrderReleaseDate`	`WorkLineNumber`, `ItemCode`
`POST /forecasts/delete`	Imported forecasts of a SKU-location	`ItemCode`, `LocationCode`

Each delete creates a task whose TaskType is Delete…, listed in Task types. Send each key exactly as you loaded the record. Dates are YYYY-MM-DD. The other kinds of inbound data, such as inventory availability, calendar overrides and vendor constraints, have no delete endpoint.

Sending a delete

POST /api/v1/supply-transactions/delete HTTP/1.1
Host: acme.gainsystems.com
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJqTl9F...
Content-Type: application/json
Idempotency-Key: 3a7e9c14-5b2d-4f81-9e6a-0c4d8b1f2a73

[
  {
    "OrderNumber": "PO-58213",
    "LineNumber": "1"
  },
  {
    "OrderNumber": "PO-58213",
    "LineNumber": "2",
    "SplitNumber": "2"
  }
]

{
  "Status": "Queued",
  "TaskId": "8d4f1a2e-6c3b-4e7a-9f05-2b1c7d9e4a60"
}

A delete follows the same rules as a load:

Rule	Detail
Size	1 to 1000 keys per request.
Checks	Each key is checked on its own. The response is `202`, `207` with the rejected keys, or `422` when none passed.
Repeats	The same key twice in one request refuses the whole request with `400`.
Access	Deleting needs delete access. Without it the request answers `403`.
Idempotency	`Idempotency-Key` is supported, as on loads.
Errors from GAINS	If GAINS cannot take the delete, the request answers `500`, `503` or `504` and creates no task. Retry later; see Load Throughput & Retries.

Follow the task as for a load. Once it is final, Batch.Accepted and Batch.Rejected count the keys GAINS deleted and refused, and Batch.RejectedRecords says why each refused key was refused.

SKU-location delete review

Deleting a SKU-location removes planning history that cannot be restored. POST /skus-locations/delete therefore deletes nothing on receipt: GAINS Connect holds the request until you approve or reject it.

How the review works

You send the SKU-locations to delete. The task starts in PendingReview. Nothing has been deleted or sent to GAINS.
You approve or reject the request with PUT /tasks/{TaskId}, using credentials that have reviewer access.
Approved: the task moves to Queued or Received and the deletion is loaded at the next scheduled load, like any other delete. It then moves to Processing and a final status.
Rejected: the task moves to RejectedNotApproved. Nothing is deleted.

While the task is PendingReview, you can withdraw it yourself (see Withdrawing a request).

{
  "Status": "PendingReview",
  "TaskId": "f17c3a9b-2e48-4d6a-8b1f-5c0e9a7d3b24"
}

Who reviews

The review is recorded through PUT /tasks/{TaskId}. It needs reviewer access. Ask your GAINS representative to grant reviewer access, preferably to credentials separate from the ones your integration uses to submit deletes. A caller without reviewer access receives 403. The reviewer is taken from the credentials that make the call, so the body carries only the decision.

{
  "Status": "approved",
  "Comments": "Discontinued at MKE02 per planning review 2026-05-21"
}

Field	Detail
`Status`	`approved` or `rejected`, in any letter case. Required.
`Comments`	Optional note, up to 1000 characters, returned on the task.

{
  "Reason": "The task has been marked as approved.",
  "Status": "Queued"
}

The decision is final: a second decision on the same task is refused with 400. Submit the delete again to get a new review.

Following the review

GET /tasks/{TaskId} shows the decision once it is made: UpdatedBy is the reviewer, UpdatedOn the time, and Comments the reviewer's note.

To be told instead of polling, enable the TaskStatusUpdate webhook trigger with a filter such as TaskType = 'DeleteSkuLocation'. See Webhooks.

Withdrawing a request

POST /tasks/{TaskId}/cancel withdraws a request that is still PendingReview, Received or Queued. The held SKU-locations are discarded and no review is needed. It answers as described in Cancelling a task.

Requests nobody reviews

A request still PendingReview 30 days after it was created is removed with its task, like every task of that age. Nothing is deleted. If you still need the deletion, send the request again.

GAINS version

The reference pages of POST /skus-locations/delete and PUT /tasks/{TaskId} state the minimum GAINS X version they need; on an older version they answer 426, see When your version is too old (426).

Related guides

Inbound Endpoints & Integration Tasks: submit responses, task statuses and following a task.
Inbound Data Model: what each key field means.
Rejected Records
Idempotency