PATCH /v1/items/{id}/stock

Scope

write_items

Request parameters

Name	In	Type	Required	Description
id	path	string	required	item_id
Idempotency-Key	header	string	required	Idempotency key (required). A UUID v4 is recommended. Resending the same key replays the original result, and the response carries Idempotent-Replay: true. Sending a different body with the same key returns 422, so always retry with the identical request.
inventory	body	integer	optional	Set stock to this absolute value (0-99999). The value overwrites the stored stock as is. ⚠️ Stored stock already excludes units held by checkouts in progress. Do not send the on-hand total (inventory + reserved_inventory) here — the held units would be counted twice, and stock ends up higher than reality once those holds are released. To match an on-hand total, use total_inventory (on environments that do not support it yet, send the difference from the total you read as adjustment). Mutually exclusive with adjustment and total_inventory.
adjustment	body	integer	optional	The amount to add or subtract (negative subtracts). A result below zero or above the maximum returns 422. Mutually exclusive with inventory and total_inventory.
total_inventory	body	integer	optional	The on-hand total (0-99999): units available now plus units held by checkouts in progress. Inside the update, the API locks the stock row, counts the units currently held, and stores total − held (0 if that would be negative). The total stays correct whether those holds are later completed or released. Do not send it together with inventory or adjustment (environments that do not support it yet drop unknown fields and would apply inventory). Sent alone to such an environment, it returns 400. Items whose stock is not tracked (null) return 422 (unlimited_inventory).
expected_total_inventory	body	integer	optional	The total you read (inventory + reserved_inventory). Only allowed together with total_inventory. When given, the API compares it with the current total and, if they differ, writes nothing and returns 409 (total_inventory_changed). The total does not change when holds are created or released; it changes when a sale completes or someone rewrites the stock. On 409, read the item and orders again and resend with a new Idempotency-Key.
variant_id	body	string	optional	Specify this to update stock for a single variant. An item that has variants carries null as its own stock, so variant_id is required for such items — omitting it returns 422.

Response example

{
  "item_id": "1408",
  "variant_id": "1",
  "inventory": 0,
  "previous_inventory": 0,
  "reserved_inventory": 0
}

Description

Update item stock, either by setting an absolute value or by applying a delta. The write is applied synchronously under a row lock. (write_items)

Error response example

{
  "error": {
    "code": "insufficient_scope",
    "message": "requires scope 'write_items'",
    "request_id": "req_01H..."
  }
}

Possible errors: 401 / 403 / 404 / 409 / 413 / 422 / 429 / 503