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

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）。指定した値でそのまま上書きします。⚠️ 在庫の値は、購入手続き中の仮押さえ分を差し引いた後の数です。手元の総数（inventory + reserved_inventory）をそのまま指定しないでください（仮押さえ分を二重に数えることになり、それが後で在庫に戻ると実数より多くなります）。総数に合わせたいときは total_inventory を使ってください（対応前の環境では、読み取った総数との差を adjustment で送ってください）。adjustment・total_inventory と排他
adjustmentボディinteger任意増減値（負=減算）。結果が負 or 上限超過は 422。inventory・total_inventory と排他
total_inventoryボディinteger任意総在庫（0〜99999）。手元の総数（いま売れる数 ＋ 購入手続き中の仮押さえ）を指定します。API が在庫の行をロックした中で仮押さえ中の数を数え、総数 − 仮押さえ中の数（0 未満なら 0）を在庫として保存します。仮押さえはその後に確定しても戻っても、総数が合うように動きます。inventory・adjustment と一緒に送らないでください（対応前の環境は、知らない項目を捨てて inventory として処理します）。対応前の環境に単独で送ると 400 です。在庫を管理していない商品（在庫が null）は 422（unlimited_inventory）
expected_total_inventoryボディinteger任意読み取ったときの総数（inventory + reserved_inventory）。total_inventory と一緒にだけ送れます。指定すると、今の総数と比べて、**違えば何も書かずに 409（total_inventory_changed）**を返します。総数は仮押さえができても戻っても変わらず、販売の確定や在庫の書き換えで変わります。409 を受けたら、商品と注文を読み直して、新しい Idempotency-Key で送り直してください
variant_idボディstring任意バリエーション単位の在庫を更新する場合に指定します。バリエーションを持つ商品は商品自体の在庫が null のため、variant_id の指定が必須です（省略すると 422）

レスポンスの例​

{
  "item_id": "1408",
  "variant_id": "1",
  "inventory": 0,
  "previous_inventory": 0,
  "reserved_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 のときは、Atouch 側の注文を取り込み、商品を読み直してから、計算し直した変動量を新しい Idempotency-Key で送ります。unlimited_inventory（在庫を管理していない商品）のときは、絶対値 inventory を指定すると在庫の管理が始まります。

在庫の値は、購入手続き中の仮押さえ分を差し引いた後の数です。 商品の応答の reserved_inventory が仮押さえ中の数で、手元の総数は inventory + reserved_inventory です。絶対値 inventory に総数をそのまま指定しないでください（仮押さえ分を二重に数えることになり、それが後で在庫に戻ると実数より多くなります）。総数を X に合わせたいときは、adjustment = X − (inventory + reserved_inventory) を送ってください。手順と注意は「概要」の「外部システムと連携する場合」にまとめています。

エラーレスポンスの例​

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

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