Release Stale Allocations
POST/api/v2/inventory-allocations/release-stale
Releases stale allocations: allocations that are still active (planned, awaiting receipt or allocated) on a sales order line that is already fully cancelled, returned or fulfilled. Each one is cancelled and its stock becomes available to other orders.
orders:writeGrant this scope to your token under Settings → Developer → Personal Access Tokens.
Every id is re-checked when the request runs; an allocation that is no longer stale (for example a fulfillment was opened on its line in the meantime) is skipped and counted in skipped, never released. Lines with a fulfillment still in progress are never stale.
List them first with GET /api/v2/inventory-allocations?filter[stale]=yes.
Body:
scope(optional,selected|all, defaultselected) —allreleases every stale allocation and ignoresidsids(required unlessscopeisall, integer[], 1–500 items) — allocation ids to release
Response data: released (count released), skipped (ids that were not stale when the request ran), remaining (with scope: all, stale allocations still left — at most 500 are released per request, so repeat until it is 0)
Requires the inventory.adjust permission.
Request
Responses
- 200
- 401
- 403
- 422
- 429
OK
Response Headers
Unauthenticated — the bearer token is missing, revoked, expired, or malformed. Never retry automatically; fix the credential. See the Errors guide.
Forbidden — the token lacks a required scope, the endpoint is not available to API tokens, or the user behind the token lacks the permission. A human must adjust the token scopes or user permissions; do not retry.
Unprocessable Content
Response Headers
Rate limited — platform limit is 1,000 requests/min; individual tokens may carry lower limits. Honor the Retry-After header before retrying. See the Rate Limits guide.