使用 API 建立批發定價

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

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

1. 端點

若要建立新的批發定價紀錄，請使用下列端點：

POST - https://wholesale.samita.io/api/v1/wholesale-pricings

2. 請求標頭

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

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

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

3. 請求內容

a. 一般格式

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

請求 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"
  }
}

b. title（必填）

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

c. status（必填）

定義該紀錄是否啟用
僅接受下列值：

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

d. apply_customer（必填）

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

結構：

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

type

可接受的值（僅能擇一）：

all – 套用於所有顧客
logged – 僅套用於已登入的顧客
non-logged – 僅套用於訪客
customer-tags – 僅套用於具有特定標籤的顧客

tags

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

若 type 不是 customer-tags，可忽略此欄位。

e. exclude_customer

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

結構：

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

type

預設值：none
可接受的值：

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

tags

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

f. apply_product（必填）

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

結構：

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

type

可接受的值：

all
products
collections
product-tags

product_ids

僅在 type == products 時必填
以逗號分隔的商品 ID 清單
範例：[1,2,3]

product_tags

僅在 type == product-tags 時必填
範例：["tag1","tag2"]

collection_ids

僅在 type == collections 時必填
範例：[1,2,3]

apply_for_variants

決定是否可依款式設定折扣
可接受的值：true 或 false
預設值：false

g. exclude_product

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

結構：

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

type

預設：none
可接受的值：

值	說明
`none`	不排除任何商品
`products`	排除特定商品
`collections`	排除特定商品系列

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

h. 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

i. apply_market（必填）

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

結構：

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

type

可接受的值：

all
specific-market

handle

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

若要取得市場 handle，請依下列步驟操作：

在 Shopify 後台中，前往 Markets 區段 > 點擊 More actions > 選擇 Edit Market handles > 複製顯示的 handle：

j. discount_group

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

在下列情況下為必填：

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

結構：

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

規則與上述折扣類型和值的規則相同。

k. active_date

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

結構：

"active_date": {
    "types": ["start_date", "end_date"],
    "start_at": "2026-01-15 10:00:00",
    "end_at": "2026-01-15 10: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 金鑰沒有 Create 權限
每組 API 金鑰可擁有下列權限：View、Create、Update、Delete
此 API 需要 Create 權限
當提供的 ID 不存在時也會傳回此錯誤

429 – Too Many Requests

超過速率限制
允許的上限：

限制	值
請求頻率	每 5 分鐘 1 次請求
每日上限	每天 50 次請求

b. 成功回應

200 – API Success

批發定價紀錄已成功建立
以 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_date", "end_date"],
    "start_at": "2026-01-15 10:00:00",
    "end_at": "2026-01-15 10:00:00"
  },
  "created_at": "2026-01-15T10:00:00",
  "updated_at": "2026-01-15T10:00:00"
}

這對您有幫助嗎？