使用 API 更新／編輯批發定價

透過公開 API 更新現有的批發定價規則，包含完整的請求內容參考。

本文說明如何使用公開 API 更新現有的批發定價規則。

1. 端點

若要更新現有的批發定價紀錄，請使用下列端點：

PUT https://wholesale.samita.io/api/v1/wholesale-pricings/{id}

{id} 為批發定價紀錄的 ID
可從應用程式介面取得 ID（不含「#」符號）
參考範例：

範例：

PUT https://wholesale.samita.io/api/v1/wholesale-pricings/1

2. 請求標頭

所有 API 請求都必須包含下列必要標頭：

標頭	說明	必填
`X-SAMITA-API-KEY`	Wholesale 應用程式中提供的 API 金鑰	是
`X-SAMITA-SHOP-URL`	Shopify 商店網域，格式為 xxx.myshopify.com	是
`CONTENT-TYPE`	必須為 `application/json`	是

若缺少任一必要標頭，請求將會被拒絕。

3. 請求內容

_ 用於更新批發定價的資料必須以 JSON 格式傳送。本文末尾提供了 JSON 結構範例。

_ 請求中只需包含要更新的欄位，不必像 Create API 方法那樣傳送所有欄位。

_ 未指定的欄位將維持不變

請求 JSON 範例：

{
  "title": "New Wholesale Pricing",
  "status": true,
  "apply_customer": {
    "type": "all",
    "tags": []
  },
  "exclude_customer": {
    "type": "none",
    "tags": []
  },
  "apply_product": {
    "type": "all",
    "product_ids": [],
    "product_tags": [],
    "collection_ids": [],
    "apply_for_variants": false
  },
  "exclude_product": {
    "type": "none",
    "product_ids": [],
    "collection_ids": []
  },
  "discount_for_variants": [
    {
      "id": 8516448190631,
      "variant_pricing": true,
      "variants": [
        {
          "id": 46747346763943,
          "discount_groups": [
            {
              "name": "all",
              "type": "percent",
              "value": "10"
            }
          ]
        }
      ]
    }
  ],
  "apply_market": {
    "type": "all",
    "handle": []
  },
  "discount_group": {
    "type": "percent",
    "value": "10"
  },
  "active_date": {
    "types": ["start_date", "end_date"],
    "start_at": "2026-01-15 10:00:00",
    "end_at": "2026-01-15 10:00:00"
  }
}

c. title

用於識別批發定價紀錄的名稱
在 Update API 中為選填
必須為字串
長度上限：255 個字元

d. status

定義該紀錄是否啟用
在 Update API 中為選填
僅接受下列值：

值	說明
`true`	定價規則已啟用
`false`	定價規則未啟用

e. apply_customer

定義哪些顧客適用此定價規則。

結構：

"apply_customer": {
    "type": "all",
    "tags": []
}

type

可接受的值：

all
logged
non-logged
customer-tags

tags

僅在 type == customer-tags 時必填
必須為以逗號分隔的陣列
範例：["wholesale","b2b"]

f. exclude_customer

用於將特定顧客排除在定價規則之外。

結構：

"exclude_customer": {
    "type": "none",
    "tags": []
}

type

預設值：none
可接受的值：

值	說明
`none`	不排除任何顧客
`customer-tags`	依標籤排除顧客

tags

僅在 type == customer-tags 時必填
範例：["vip","wholesale"]

g. apply_product（必填）

定義定價規則將套用於哪些商品。

結構：

"apply_product": {
    "type": "all",
    "product_ids": [],
    "product_tags": [],
    "collection_ids": [],
    "apply_for_variants": false
}

type

可接受的值：

all
products
collections
product-tags

其他欄位是否必填，取決於所選的 type：

product_ids → 若 type == products 則為必填
product_tags → 若 type == product-tags 則為必填
collection_ids → 若 type == collections 則為必填

apply_for_variants

可接受的值：true 或 false
預設值：false

h. exclude_product

定義要從規則中排除的商品。

結構：

"exclude_product": {
    "type": "none",
    "product_ids": [],
    "collection_ids": []
}

可接受的類型：

none
products
collections

i. discount_for_variants

用於依款式設定折扣的情況。

若 apply_product.apply_for_variants == false，必須為空
若 apply_product.apply_for_variants == true，則為必填

範例結構：

"discount_for_variants": [
  {
    "id": 8516448190631,
    "variant_pricing": true,
    "variants": [
      {
        "id": 46747346763943,
        "discount_groups": [
          {
            "name": "all",
            "type": "percent",
            "value": "10"
          }
        ]
      }
    ]
  }
]

結構：

商品陣列
每個商品包含：
- id – 商品 ID
- variant_pricing – 必須為 true
- variants – 款式陣列

每個款式包含：

id – 款式 ID
discount_groups – 折扣設定陣列

discount_groups 規則

若 apply_customer.type 為 all、logged 或 non-logged
→ 僅允許一個項目
若 apply_customer.type == customer-tags
→ 可提供多個折扣群組

discount_groups 內的欄位：

欄位	說明
`name`	必須符合顧客類型或顧客標籤
`type`	折扣類型
`value`	折扣值

可接受的折扣類型：

percent
amount
fixed-amount

數值規則：

必須為大於 0 的數字
若 type 為 percent，值必須小於 100

j. apply_market（必填）

定義規則適用於哪些 Shopify 市場。

結構：

"apply_market": {
    "type": "all",
    "handle": []
}

type

可接受的值：

all
specific-market

handle

僅在 type == specific-market 時必填
以逗號分隔的市場 handle 清單
範例：["japan","us"]

k. discount_group

用於未依款式設定折扣的情況。

在下列情況下為必填：

apply_product.type 不是 products，或
apply_product.type == products 且未套用款式

結構：

"discount_group": {
    "type": "percent",
    "value": "10"
}

規則：

type 必須為下列其中之一：
- percent
- amount
- fixed-amount
value
- 必須大於 0
- 若 type 為 percent，值必須小於 100

l. active_date

用於設定定價規則的開始與結束時間。

結構：

"active_date": {
    "types": ["start_date", "end_date"],
    "start_at": "2026-01-15T10:00:00",
    "end_at": "2026-01-15T10:00:00"
}

types

選填
可接受的值：start_date、end_date
範例：["start_date","end_date"]

start_at

若 types 包含 start_date，則為必填
格式：YYYY-MM-DD HH:MM:SS

end_at

若 types 包含 end_date，則為必填
格式：YYYY-MM-DD HH:MM:SS

4. API 回應

a. 錯誤回應

401 – Unauthorized

可能原因：

缺少商店網址
缺少 API 金鑰
商店網址無效
API 金鑰無效
API 金鑰與商店不符

403 – This action is unauthorized

API 金鑰沒有 Update 權限
每組 API 金鑰可擁有下列權限：View、Create、Update、Delete
此 API 需要 Update 權限
當提供的 ID 不存在時也會傳回此錯誤

429 – Too Many Requests

超過速率限制：

上限為每 5 分鐘 1 次請求
上限為每天 50 次請求

b. 成功回應

200 – API Success

批發定價紀錄已成功更新
以 JSON 格式傳回回應

回應 JSON 範例：

{
  "id": 1,
  "title": "New Wholesale Pricing",
  "status": true,
  "apply_customer": {
    "type": "all",
    "tags": []
  },
  "exclude_customer": {
    "type": "none",
    "tags": []
  },
  "apply_product": {
    "type": "all",
    "product_ids": [],
    "product_tags": [],
    "collection_ids": [],
    "apply_for_variants": false
  },
  "exclude_product": {
    "type": "none",
    "product_ids": [],
    "collection_ids": []
  },
  "discount_for_variants": [
    {
      "id": 8516448190631,
      "variant_pricing": true,
      "variants": [
        {
          "id": 46747346763943,
          "discount_groups": [
            {
              "name": "all",
              "type": "percent",
              "value": "10"
            }
          ]
        }
      ]
    }
  ],
  "apply_market": {
    "type": "all",
    "handle": []
  },
  "discount_group": {
    "type": "percent",
    "value": "10"
  },
  "active_date": {
    "types": [],
    "start_at": "",
    "end_at": ""
  },
  "created_at": "2026-01-15T10:00:00",
  "updated_at": "2026-01-15T10:00:00"
}

這對您有幫助嗎？