Release Inventory Hold

POST 
/api/v2/inventory/holds/:reservation/release

Releases inventory from a hold. Supports both partial and full release.

Required scope: inventory:write

Grant this scope to your token under Settings → Developer → Personal Access Tokens.

Partial release (quantity provided AND less than current held quantity):

• The hold's quantity is reduced by the released amount
• released_quantity accumulates the cumulative total released across all release events
• released_at remains null — the hold is still active

Full release (quantity omitted, null, 0, or equal to current held quantity):

• released_at, released_by, and release_reason are populated
• The remaining quantity is added to released_quantity so it reflects the cumulative total released

Authentication: Requires Bearer token.

Request Body:

• quantity (nullable, numeric, min 0.0001, max=current held quantity): Quantity to release. Omit, send null, or send 0 to fully release. Cannot exceed the current held quantity (returns 422)
• release_reason (nullable, string, max 500): Reason for the release

Requires permission: inventory.adjust

Request

Responses

200

OK

401

Unauthenticated — the bearer token is missing, revoked, expired, or malformed. Never retry automatically; fix the credential. See the Errors guide.

403

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.

404

Not found — no record with the given identifier (or the route does not exist). Verify the ID before retrying.

422

Unprocessable Entity

429

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.