メインコンテンツまでスキップ

PATCH /v1/items/{id}/stock

scope​

write_items

リクエストパラメーター​

名前位置型必須説明
idパスstring必須item_id
Idempotency-Keyヘッダーstring必須冪等キー（必須）。UUID v4 を推奨します。同一キーの再送は最初の結果をそのまま再生し、応答に Idempotent-Replay: true が付きます。同一キーで異なるボディを送ると 422 になるため、リトライは必ず同一リクエストで行ってください
inventoryボディinteger任意絶対値 SET（0〜99999）。adjustment と排他
adjustmentボディinteger任意増減値（負=減算）。結果が負 or 上限超過は 422。inventory と排他
variant_idボディstring任意バリエーション単位の在庫を更新する場合に指定します。バリエーションを持つ商品は商品自体の在庫が null のため、variant_id の指定が必須です（省略すると 422）

レスポンスの例​

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

解説​

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

外部システム（他の EC 等）と在庫を同期する場合は、原則として adjustment（変動量）を使ってください。絶対値 inventory を定期的に流す運用は、送信の間に Atouch 側で発生した販売を上書きし、在庫を過大に戻します（＝売り越しの原因）。絶対値を使うのは初回の投入と定期的な突合に限るのが安全です。adjustment が 422（negative_inventory / unlimited_inventory）で失敗した場合は、その変動量を捨てずに絶対値 SET で再同期してください（失敗を無視すると差分が失われたまま進みます）。

エラーレスポンスの例​

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

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