在庫管理API（Inventory / WMS API）の使い方

API 在庫管理 WMS OAuth MCP Shopify連携

在庫管理API（Inventory / WMS API）を使うと、ビジネスアカウントの在庫をロケーション（倉庫・店舗バックヤード・売場）単位で照会・調整できます。Shopify ロケーションと対応付けされている場合、API からの在庫調整は自動的に Shopify にも反映されます。

必要なスコープ

store.inventory.read — 在庫・ロケーション・移動履歴の取得
store.inventory.write — 在庫の調整

アプリケーション登録時にスコープをリクエストし、ビジネスオーナーの同意を得てください。認証フローは API認証ガイドをご覧ください。

エンドポイント一覧

GET /api/v1/inventory — 在庫一覧（locationId / productId / lowStock=true で絞り込み）
GET /api/v1/inventory/{locationId}/{productId} — 在庫詳細
GET /api/v1/inventory/locations — ロケーション一覧
POST /api/v1/inventory/adjust — 在庫調整
GET /api/v1/inventory/movements — 在庫移動履歴

在庫を照会する

在庫一覧はロケーション×商品ごとに1行返ります。lowStock=true を付けると、発注点（最小在庫数）を下回っている行だけに絞り込めます。

GET /api/v1/inventory?organizationId={orgId}&lowStock=true
Authorization: Bearer {access_token}

{
  "count": 2,
  "stock": [
    {
      "locationId": "loc-001",
      "locationName": "本店バックヤード",
      "productId": "prd-001",
      "productName": "有機マンゴージュース",
      "sku": "MNG-001",
      "quantity": 3,
      "availableQuantity": 3,
      "minStockLevel": 10,
      "isLowStock": true
    }
  ]
}

在庫を調整する

符号付きの数量変化と理由を指定します。プラスで入荷、マイナスで出庫・廃棄です。調整は移動履歴に記録され、担当者名と理由が残ります。

POST /api/v1/inventory/adjust?organizationId={orgId}
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "locationId": "loc-001",
  "productId": "prd-001",
  "quantityChange": -3,
  "reason": "破損廃棄"
}

対象の在庫行が存在しない場合は 404 が返ります。在庫行は入荷処理や棚卸しで商品がロケーションに初めて登録されたときに作成されます。

Shopify 連携時の自動反映

ビジネスアカウントが Shopify と連携していて、対象ロケーションが Shopify ロケーションと対応付けされている場合、API からの在庫調整は自動的に Shopify 側にも反映されます。追加の API 呼び出しは不要です。逆方向（Shopify 側の在庫変動）も Webhook 経由でレシートローラーに反映されます。

移動履歴を取得する

入荷・移動・棚卸し・調整（Shopify 同期由来を含む）の履歴を新しい順に取得できます。

GET /api/v1/inventory/movements?organizationId={orgId}&productId=prd-001
Authorization: Bearer {access_token}

MCP ツールから使う

ChatGPT や Claude などの AI エージェントからは、MCP サーバー（https://mcp.receiptroller.io）経由で同じ機能を利用できます。

wms_get_stock — 在庫照会（lowStock フィルタ対応）
wms_list_locations — ロケーション一覧
wms_adjust_stock — 在庫調整
wms_list_movements — 移動履歴

商品（pim_*）・注文（oms_*）のツールも同じ MCP サーバーで提供しています。MCP の接続方法は AIエージェント連携（MCP）をご覧ください。