庫存管理 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 — 庫存異動紀錄

查詢庫存

庫存一覽會依據點 × 商品各回傳一列。加上 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 反映至 ReceiptRoller。

取得異動紀錄

可依新到舊的順序取得入庫、異動、盤點、調整（含 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）。