使用 API 创建 Volume Pricing

通过公共 API 创建新的 Volume Pricing 规则，包含完整的请求正文参考。

本文介绍如何使用公共 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，value 必须小于 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，value 必须小于 100

j. apply_market（必填）

定义规则适用于哪些 Shopify 市场。

结构：

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

type

可接受的值：

all
specific-market

handle

仅当 type == specific-market 时必填
以逗号分隔的市场 handle 列表
示例：["japan","us"]

要获取市场 handle，请按以下步骤操作：

在 Shopify 后台页面中，进入市场部分 > 点击 更多操作 > 选择 编辑市场 handle > 复制其中显示的 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"
}

这对您有帮助吗？