PATCH /v1/items/{id}/stock

scope

write_items

リクエストパラメーター

名前	位置	型	必須	説明
id	パス	integer	必須	item_id
Idempotency-Key	ヘッダー	string	必須	冪等キー（必須・ADR-010）。UUID v4 推奨。同一キー再送は保存レスポンスを再生
inventory	ボディ	integer	任意	絶対値 SET（0〜99999）。adjustment と排他
adjustment	ボディ	integer	任意	増減値（負=減算）。結果が負 or 上限超過は 422。inventory と排他

レスポンスの例

{
  "item_id": 0,
  "inventory": 0,
  "previous_inventory": 0
}

解説

商品在庫を更新します。inventory（絶対値 SET・0〜99999）または adjustment（増減値・負=減算）のどちらか一方だけを指定します。増減の結果が負・上限（99999）超過は 422。在庫無制限（null）の商品に adjustment は適用できず 422、絶対値 inventory の指定で追跡在庫へ切り替えられます。set 商品（在庫は構成品から自動計算）と、バリエーションで在庫管理する商品も 422（variant_id 対応は順次開放）。レスポンスの inventory / previous_inventory は行ロック下で確定した実値です（レプリカ遅延に依存しません）。変更はマーチャントの修正ログに記録されます。Idempotency-Key 必須。

エラーレスポンスの例

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

返しうるエラー: 401 / 403 / 404 / 422 / 503