使用 API 建立 Volume Pricing

透過 Public API 建立新的 Volume Pricing 規則，包含完整的請求本文參考。

本文件說明如何使用 Public API 建立新的 Volume Pricing 規則。

1. 端點

若要建立新的 Volume Pricing 記錄，請使用下列端點：

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

此端點可讓您建立新的 Volume Pricing 設定。

2. 請求標頭

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

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

若缺少任何必填標頭，請求將被拒絕。

3. 請求本文

a. 一般格式

用來建立 Volume Pricing 的資料必須以 JSON 格式傳送。
本文件末尾提供了範例 JSON 結構。

範例請求 JSON：

{
  "title": "New Volume Pricing",
  "status": true,
  "type": "quantity",
  "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,
      "duplicated": false,
      "variant_pricing": true,
      "from_qty": "0",
      "from_amount": "0",
      "to_qty": "10",
      "to_amount": "0",
      "discount_groups": [
        {
          "name": "all",
          "type": "percent",
          "value": "10"
        }
      ],
      "variants": [
        {
          "id": 46747346763943,
          "duplicated": false,
          "from_qty": "0",
          "from_amount": "0",
          "to_qty": "10",
          "to_amount": "0",
          "discount_groups": [
            {
              "name": "all",
              "type": "percent",
              "value": "10"
            }
          ]
        }
      ]
    }
  ],
  "apply_market": {
    "type": "all",
    "handle": []
  },
  "discount_method": "variant",
  "discount_groups": [
    {
      "from_qty": "0",
      "from_amount": "0",
      "to_qty": "10",
      "to_amount": "0",
      "type": "percent",
      "value": "10"
    }
  ],
  "active_date": {
    "types": ["start date", "end date"],
    "start_at": "2026-01-15T10:00:00",
    "end_at": "2026-01-15T10:00:00"
  }
}

b. title（必填）

用來識別 Volume Pricing 記錄的名稱
必須為字串
最大長度：255 個字元

c. status（必填）

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

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

d. type（必填）

定義 Volume Pricing 是依數量還是依金額計算。

可接受的值：

quantity
amount

e. apply_customer（必填）

定義哪些顧客符合此定價規則。

結構：

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

type

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

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

tags

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

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

f. exclude_customer

用來從定價規則中排除特定顧客。

結構：

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

type

預設值：none
可接受的值：

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

tags

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

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

h. exclude_product

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

結構：

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

type

預設：none
可接受的值：

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

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

i. discount_for_variants

定義商品及／或款式層級的折扣設定。

若 apply_product.apply_for_variants == false，請將此欄位留空。
若 apply_product.apply_for_variants == true，則此欄位為必填。
結構必須為商品設定的陣列。

結構：

"discount_for_variants": [
    {
      "id": 8516448190631,
      "duplicated": false,
      "from_qty": "0",
      "from_amount": "0",
      "to_qty": "10",
      "to_amount": "0",
      "discount_groups": [
        {
          "name": "all",
          "type": "percent",
          "value": "10"
        }
      ],
      "variant_pricing": true,
      "variants": [
        {
          "id": 46747346763943,
          "duplicated": false,
          "from_qty": "0",
          "from_amount": "0",
          "to_qty": "10",
          "to_amount": "0",
          "discount_groups": [
            {
              "name": "all",
              "type": "percent",
              "value": "10"
            }
          ]
        }
      ]
    }
]

i.1. id（必填）

商品 ID。
必須與現有商品相符。

i.2. duplicated

表示商品是否有多個數量／金額區間。

可接受的值：

true
false

規則：

若為 true：商品包含多個數量／金額區間。
若為 false：商品只有一個數量／金額區間。

i.3. from_qty / from_amount

區間的起始數量或金額。

規則：

第一個項目可以留空（預設為 1）。
之後的所有項目皆為必填。

i.4. to_qty / to_amount

區間的結束數量或金額。

規則：

可以留空（將自動計算為下一個項目的 from 值減 1）。
若有提供，必須小於下一個項目的 from 值。

範例：

項目 1：from:0 – to:10 → 項目 2：from:11 – to:20
項目 1：from:0 – to:blank → 項目 2：from:10 – to:blank
項目 1：from:blank – to:10 → 項目 2：from:11 – to:blank

i.5. discount_groups（商品層級）

定義商品層級中每個數量／金額區間的折扣設定。

若 variant_pricing == false，則為必填。
若 variant_pricing == true，請留空。
必須是與所設定的 apply_customer.type 對應的折扣物件陣列。

結構：

{
    "name": "all",
    "type": "percent",
    "value": "10"
}

+ name

可接受的值：

all（若 apply_customer.type == all）
logged（若 apply_customer.type == logged）
non-logged（若 apply_customer.type == non-logged）

若提供其他值，會被視為顧客標籤，且必須與 apply_customer.tags 中定義的其中一個標籤相符。

+ type

定義折扣類型。

可接受的值：

percent：百分比折扣
amount：從價格中扣除的固定金額
fixed-amount：最終固定價格

+ value

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

i.6. variant_pricing

表示是否在款式層級套用折扣。

可接受的值：

true
false

i.7. variants

定義款式層級的折扣設定。

若 variant_pricing == true，則為必填
若 variant_pricing == false，請留空
必須為款式設定的陣列

結構：

{
  "id": 46747346763943,
  "duplicated": false,
  "from_qty": "0",
  "from_amount": "0",
  "to_qty": "10",
  "to_amount": "0",
  "discount_groups": [
    {
      "name": "all",
      "type": "percent",
      "value": "10"
    }
  ]
}

+ id（必填）

款式 ID。

+ duplicate

表示款式是否有多個數量／金額區間。

可接受的值：

true
false

規則：

若為 true：款式包含多個區間。
若為 false：款式只有一個區間。

+ from_qty / from_amount

起始數量或金額。

規則：

第一個項目可以留空（預設為 1）。
之後的所有項目皆為必填。

+ to_qty / to_amount

結束數量或金額。

規則：

可以留空（自動計算為下一個項目的 from 減 1）。
若有提供，必須小於下一個項目的 from 值。

範例：

項目 1：from:0 – to:10 → 項目 2：from:11 – to:20
項目 1：from:0 – to:blank → 項目 2：from:10 – to:blank
項目 1：from:blank – to:10 → 項目 2：from:11 – to:blank

+ discount_groups（款式層級）

定義款式層級中每個數量／金額區間的折扣設定。

規則：

若 apply_customer.type 為：
- all
- logged
- non-logged
  → 陣列只能包含一個項目。
若 apply_customer.type == customer-tags
→ 陣列必須包含多個項目（每個顧客標籤一個）。

name

可接受的值：

all
logged
non-logged

若提供其他值，會被視為顧客標籤，且必須與 apply_customer.tags 中定義的標籤相符。

type

可接受的值：

percent
amount
fixed-amount

value

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

j. 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：

k. discount_methods（必填）

可接受的值：

variant → Same Variant
across_group → Mix Variants
within_each_group → Mix Products

這些對應於應用程式中可用的選項。

範例：

"discount_method": "variant",

l. discount_group（必填）

定義數量／金額區間及折扣值。

from_qty / from_amount

to_qty / to_amount

驗證規則與上述相同。

可接受的「type」值：

percent
amount
fixed-amount

value：

必須 > 0
若為 percent → 必須 < 100

結構：

"discount_groups": [
    {
      "from_qty": "0",
      "from_amount": "0",
      "to_qty": "10",
      "to_amount": "0",
      "type": "percent",
      "value": "10"
    }
  ],

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

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

可能的原因：

缺少商店 URL
缺少 API 金鑰
商店 URL 無效
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

Volume Pricing 記錄已成功建立
回應以 JSON 格式傳回

{
  "id": 1,
  "title": "New Volume Pricing",
  "status": true,
  "type": "quantity",
  "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,
      "duplicated": false,
      "variant_pricing": true,
      "from_qty": "0",
      "from_amount": "0",
      "to_qty": "10",
      "to_amount": "0",
      "discount_groups": [
        {
          "name": "all",
          "type": "percent",
          "value": "10"
        }
      ],
      "variants": [
        {
          "id": 46747346763943,
          "duplicated": false,
          "from_qty": "0",
          "from_amount": "0",
          "to_qty": "10",
          "to_amount": "0",
          "discount_groups": [
            {
              "name": "all",
              "type": "percent",
              "value": "10"
            }
          ]
        }
      ]
    }
  ],
  "apply_market": {
    "type": "all",
    "handle": []
  },
  "discount_method": "variant",
  "discount_groups": [
    {
      "from_qty": "0",
      "from_amount": "0",
      "to_qty": "10",
      "to_amount": "0",
      "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"
}

這對您有幫助嗎？