Volume Pricing 的 API

本文件說明如何使用 Public API 取得 Volume Pricing 記錄清單。

---

1. 端點

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

此端點可讓您依篩選與排序參數取得 Volume Pricing 記錄清單。

---

2. 請求標頭

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

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

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

---

3. 請求參數

GET 請求支援下列選填的查詢參數：

---

a. limit

定義傳回記錄的最大數量。

• 必須為數字
• 最小值：1
• 最大值：20
• 若留空，預設值為 20

範例：

?limit=10

---

b. query

用來依標題或 ID 篩選記錄的搜尋字串。

• 必須為字串
• 最大長度：255 個字元

範例：

?query=pricing rule

---

c. status

依狀態篩選記錄。

• 可留空以取得所有記錄

• 若有提供，僅接受下列值：

  值	說明
  active	僅限啟用中的記錄
  draft	僅限草稿記錄

範例：

?status=active

---

d. sort

依建立時間排序記錄。

• 可留空（預設：最新的記錄在前）
• 若有提供，僅接受下列其中一個值：
  • descrease
  • ascrease

範例：

?sort=descrease

---

完整請求範例

GET https://wholesale.samita.io/api/v1/volume-pricings?limit=10&status=active&sort=descrease

---

4. API 回應

---

4.1 錯誤回應

401 – Unauthorized

驗證失敗時傳回。

可能的原因：

• 缺少商店 URL
• 缺少 API 金鑰
• 商店 URL 不正確
• API 金鑰不正確
• API 金鑰與商店不符

---

403 – This action is unauthorized

API 金鑰權限不足時傳回。

每個 API 金鑰可指派下列權限：

• View
• Create
• Update
• Delete

List Volume Pricing API 需要 View 權限。

---

429 – Too Many Requests

超過速率限制時傳回。

目前的限制：

• 最多每 5 分鐘 1 次請求
• 最多每天 50 次請求

---

4.2 成功回應

200 – API Success

請求有效且成功處理時傳回。

回應會以 JSON 格式傳回 Volume Pricing 記錄清單。

---

API 成功回應範例：

[
  {
    "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"
  }
]