變體商品搞不定？資深工程師的 WooCommerce 商品 API 終極指南：從屬性到庫存全自動化！

哈囉，大家好！我是浪花科技的資深工程師 Eric。如果你有在玩 WooCommerce，那你一定知道，用 REST API 來自動化處理商品上下架、同步庫存，真的是一件爽度破表的事。我們之前也聊過 WooCommerce 商品 API 的基本實戰，相信很多朋友都已經能輕鬆處理簡單商品 (Simple Product) 了。

但是，當你碰到「可變商品」(Variable Product) 時，是不是瞬間覺得事情變得複雜起來？什麼顏色、尺寸、規格…光是在後台手動設定，就已經夠讓人頭痛了，更何況是用 API 來處理。那種感覺，就像你以為你在寫 CRUD，結果發現是在解一個俄羅斯方塊，一個蘿蔔一個坑，錯一步就全盤皆輸。別怕，今天這篇文章，就是來拯救你脫離這個苦海的。身為一個踩過無數坑的工程師，我會帶你一步步拆解可變商品的結構，讓你從此用 API 操控變體商品就像呼吸一樣自然。

為什麼「可變商品」透過 API 操作特別棘手？

在我們捲起袖子開始寫 code 之前，先搞懂敵人是誰很重要。可變商品在 WooCommerce 的資料庫裡，並不是一個單純的物件，它其實是一個「家族」。

• 家長（父項商品）： 這是你商店頁面上看到的主要商品，它本身沒有價格、沒有庫存，只是一個容器，用來定義共享的資訊，像是商品描述、分類，以及最重要的——有哪些「屬性」可以用來變化，例如「顏色」和「尺寸」。
• 小孩（變化形態）： 每一個具體的商品選項，例如「紅色、S 號」或「藍色、M 號」，都是一個獨立的「變化形態」(Variation)。它們繼承了家長的描述，但擁有自己獨立的 SKU、價格、庫存、圖片等等。

所以，當我們想用 API 建立一個完整的可變商品時，流程就變成了：

1. 告訴 WooCommerce：「嘿，我要建立一個『可變商品』的家長喔！」
2. 告訴這個家長：「你有『顏色』和『尺寸』這兩種屬性可以玩。」
3. 接著，一個一個地告訴 WooCommerce：「幫我建立一個『紅色 S 號』的小孩，它的價格是 500 元，庫存 10 件。」、「再幫我建立一個『藍色 M 號』的小孩…」

看出來了嗎？這中間的關聯性與步驟，就是它棘手的地方。只要一個環節的 JSON 格式送錯，或是 ID 沒對上，API 就會毫不留情地回你一個 `400 Bad Request`，讓你對著螢幕懷疑人生。

前置準備：API 金鑰與你的除錯好夥伴

在開始實戰之前，請確保你已經在 WooCommerce 後台的「設定」>「進階」>「REST API」中，產生了一組具備「讀取/寫入」權限的 API 金鑰 (Consumer Key & Consumer Secret)。這就像是你進入自動化世界的門票，我就不多贅述了。

另外，身為一個工程師，我強烈建議你準備一個好用的 API 測試工具，像是 Postman 或 Insomnia。它們能幫你輕鬆地組織 API 請求、管理驗證資訊，並且用非常友善的介面呈現回傳的 JSON 結果，絕對是你除錯時的最佳戰友。當然，如果你是終端機的死忠粉絲，`curl` 也是你的好朋友！

實戰第一步：定義「全域屬性」，打好資料地基

在建立商品之前，我們要先建立變化的基礎——屬性 (Attributes)。在 WooCommerce 中，屬性有兩種：一種是只屬於單一商品的「自訂商品屬性」，另一種是可以在全站重複使用的「全域屬性」。

身為一個有程式潔癖的工程師，我強烈建議你使用「全域屬性」。為什麼？因為這樣才能確保資料的一致性。你不會希望你的資料庫裡同時存在「顏色」、「Color」、「色彩」這三種其實是同樣意義的屬性吧？這對未來的篩選和管理會是場災難。所以，我們先來建立「尺寸 (Size)」這個全域屬性。

使用 API 建立屬性 (Attribute)

首先，我們要告訴 WooCommerce：「嘿，我需要一個叫做『Size』的屬性。」

Endpoint: `POST /wp-json/wc/v3/products/attributes`

{
  "name": "Size",
  "slug": "size",
  "type": "select",
  "order_by": "menu_order",
  "has_archives": true
}

成功後，你會收到一個回傳，裡面包含了這個屬性的 ID，例如 `id: 1`。記下這個 ID，我們馬上會用到。

為屬性新增詞彙 (Terms)

有了「Size」這個屬性，我們還需要為它加上可選的項目，例如 S, M, L。這些項目在 WooCommerce 裡叫做「詞彙 (Terms)」。

Endpoint: `POST /wp-json/wc/v3/products/attributes/1/terms` (注意，這裡的 `1` 就是我們剛剛拿到的屬性 ID)

// 建立 S
{
  "name": "S"
}

// 建立 M
{
  "name": "M"
}

// 建立 L
{
  "name": "L"
}

你需要分次呼叫 API 來建立每一個詞彙。當然，你也可以使用批次更新的端點 `…/terms/batch` 來一次搞定，這在你有大量詞彙時特別有用。

實戰第二步：建立「可變商品」父項 (Parent)

地基打好了，現在可以來蓋房子了。我們要建立一個 `type` 為 `variable` 的商品，並告訴它要使用我們剛剛建立的 `Size` 屬性。

Endpoint: `POST /wp-json/wc/v3/products`

{
  "name": "工程師風格 T-Shirt",
  "type": "variable",
  "description": "一件穿上去 Code 就能自己動起來的神奇 T-shirt。",
  "categories": [
    { "id": 9 }
  ],
  "attributes": [
    {
      "id": 1,          // 這是全域屬性的 ID
      "position": 0,
      "visible": true,    // 在商品頁面上可見
      "variation": true,  // 這個屬性要用來做變化形態
      "options": [
        "S",
        "M",
        "L"
      ]
    }
  ],
  "default_attributes": [
    {
      "id": 1,
      "option": "M"      // 預設選中的尺寸
    }
  ]
}

這裡有幾個魔鬼細節，請睜大眼睛：

• `type` 必須是 `variable`。
• `attributes` 是一個陣列。裡面的物件 `id` 指向我們建立的全域屬性 ID (`1`)。
• `variation` 旗標一定要設為 `true`！這是在告訴 WooCommerce：「這個屬性是用來組合出不同小孩的關鍵！」很多人卡關都是因為忘了這個。
• `options` 裡面列出這個商品會用到哪些詞彙。

成功後，你會拿到這個父項商品的 ID，例如 `id: 123`。記下來，這是家長的身份證號碼！

實戰第三步：為父項商品新增「變化形態」(Variations)

家長誕生了，接下來就是生小孩的時候了。我們要針對 `product_id: 123` 來新增它的變化形態。

Endpoint: `POST /wp-json/wc/v3/products/123/variations` (這裡的 `123` 就是父項商品的 ID)

// 建立 S 號的變化形態
{
  "regular_price": "800",
  "stock_quantity": 20,
  "sku": "TSHIRT-SIZE-S",
  "attributes": [
    {
      "id": 1,
      "option": "S"
    }
  ]
}

看到了嗎？`attributes` 陣列在這裡扮演了「指定身份」的角色。`”id”: 1, “option”: “S”` 就明確定義了這是由 `Size` 屬性的 `S` 選項所構成的變化形態。你可以重複呼叫這個 API 來建立 M 號、L 號的變化形態。

工程師的浪漫：批次建立所有變化形態

一個一個建立太慢了，不符合我們追求效率的工程師精神。幸好，WooCommerce API 提供了批次處理的端點，讓我們可以一次把所有小孩都生出來！

Endpoint: `POST /wp-json/wc/v3/products/123/variations/batch`

{
  "create": [
    {
      "regular_price": "800",
      "stock_quantity": 20,
      "sku": "TSHIRT-SIZE-S",
      "attributes": [
        { "id": 1, "option": "S" }
      ]
    },
    {
      "regular_price": "800",
      "stock_quantity": 50,
      "sku": "TSHIRT-SIZE-M",
      "attributes": [
        { "id": 1, "option": "M" }
      ]
    },
    {
      "regular_price": "850", // L 號比較貴
      "stock_quantity": 15,
      "sku": "TSHIRT-SIZE-L",
      "attributes": [
        { "id": 1, "option": "L" }
      ]
    }
  ]
}

用一個 `create` 陣列把所有要建立的變化形態包起來，一次請求，全部搞定。這才是自動化該有的樣子嘛！

日常維護：更新庫存與價格

商品建立完只是第一步，真正的日常維護，像是同步 ERP 的庫存、根據活動調整價格，才是 API 發揮最大價值的地方。更新一個變化形態非常簡單，你只需要知道它的 ID。

假設 M 號的變化形態 ID 是 `456`，我們想把它的庫存更新為 45。

Endpoint: `PUT /wp-json/wc/v3/products/123/variations/456`

{
  "stock_quantity": 45
}

就這麼簡單！你可以寫一個排程，每天半夜自動去同步 ERP 系統的庫存，從此告別手動 key in 的惡夢。

結論：解放你的雙手，讓程式碼為你工作

管理 WooCommerce 的可變商品，尤其是當你有成百上千種組合時，手動操作無疑是一場災難。但一旦你掌握了透過 REST API 操作它們的技巧，你就等於擁有了一把解放生產力的鑰匙。

從建立全域屬性、定義可變商品父項，到批次生成所有變化形態，再到日常的庫存價格更新，整個流程雖然比簡單商品複雜，但邏輯是清晰的。只要你理解了「父項-屬性-變化形態」這個核心概念，並小心處理好 JSON 中的各個 ID 與旗標，你就能打造出強大且穩定的自動化商品管理系統。

延伸閱讀

• 告別手動上架地獄！WooCommerce 商品 API 終極實戰，讓你的庫存、ERP 同步自動化！
• 你的庫存同步還在龜速跑迴圈？WooCommerce 商品 API 批次處理終極指南，效能原地起飛！
• 告別手動複製貼上！WooCommerce Webhook 終極指南：打造零失誤、全自動的訂單處理流程

如果你在實作中遇到了任何問題，或是對於更複雜的電商自動化流程（例如整合 ERP、PIM 系統）有興趣，別猶豫，浪花科技的團隊隨時準備好為你提供專業的技術支援。歡迎點擊這裡，填寫表單與我們聯繫，讓我們一起打造更高效、更智慧的電商解決方案！