# 折扣

> Shoplazza CLI 的 discounts 命令：创建优惠码、闪购和满减活动的快捷命令，以及营销活动背后的 API 命令。

管理折扣、优惠券和营销活动。包含 8 个快捷命令和 15 个 API 命令。

## 快捷命令

### +search

搜索已有折扣。

```shell
shoplazza discounts +search [flags]
```

| 参数 | 类型 | 说明 |
|------|------|------|
| `--query` | string | 按折扣名称模糊搜索 |
| `--discount-code` | string | 按折扣码搜索 |
| `--progress` | string | 进度过滤：`ongoing`、`not_started`、`finished`、`paused` |
| `--discount-type` | string | 折扣类型过滤 |
| `--discount-target` | string | 目标过滤：`product`、`order`、`shipping` |
| `--discount-method` | string | 方式过滤：`automatic`、`discount_code` |
| `--page-limit` | int | 页面大小（1–250） |

```shell
shoplazza discounts +search
shoplazza discounts +search --query "Summer"
shoplazza discounts +search --discount-code SALE20
shoplazza discounts +search --progress ongoing --discount-type flashsale
```

### +rebate

创建自动阶梯满减（满额减/满件折）。

```shell
shoplazza discounts +rebate [flags]
```

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `--target` | string | 是 | 范围：`order` 或 `product` |
| `--tiers` | string | 是 | 阈值:折扣 对（逗号分隔，如 `100:10,200:25`） |
| `--type` | string | | 类型：`amount-off`、`amount-percent`、`qty-off`、`qty-percent`（默认：`amount-off`） |
| `--products` | string | | 商品 ID（逗号分隔）；`--target product` 时 `--products`/`--collections`/`--variants` 必须提供其一 |
| `--collections` | string | | 集合 ID（与 `--products` 互斥） |
| `--variants` | string | | 变体 ID（与 `--products` 互斥） |
| `--exclude` | bool | | 将 ID 作为排除列表（默认：`false`） |
| `--limit-max` | int | | 最大总使用次数 |
| `--limit-user` | int | | 每用户最大使用次数 |
| `--limit-order-once` | bool | | 每单最多应用一次（默认：`true`；仅适用于 `--type amount-off` 或 `qty-off`） |
| `--combines` | string | | 允许叠加：`order`、`product`、`shipping` |
| `--customer-segments` | string | | 限定客户群 ID |
| `--name` | string | | 活动名称（不填则自动生成） |
| `--start` | string | | 开始时间（默认：`now`） |
| `--end` | string | | 结束时间（默认：`-1`，永不过期） |

```shell
# 订单满 100 减 10，满 200 减 25
shoplazza discounts +rebate --target order --tiers "100:10,200:25"

# 商品满 3 件打 8 折
shoplazza discounts +rebate --target product --type qty-percent \
  --tiers "3:20" --products "id1,id2"
```

### +flashsale

创建限时特卖（自动折扣）。

```shell
shoplazza discounts +flashsale [flags]
```

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `--value` | float | 是 | 折扣值：percent → 1–99；fixed-price → 新价格；off → 减免金额 |
| `--type` | string | | 类型：`percent`、`fixed-price`、`off`（默认：`percent`） |
| `--variants` | string | | 变体 ID（与 `--collections` 互斥） |
| `--collections` | string | | 集合 ID（与 `--variants` 互斥） |
| `--price-rule` | string | | 基于价格：`price`（售价）或 `compare_at_price`（默认：`price`） |
| `--limit-user-variant` | int | | 每用户每变体最大购买量 |
| `--limit-user-product` | int | | 每用户每商品最大购买量 |
| `--limit-user-all` | int | | 每用户跨所有活动商品最大购买量 |
| `--stock` | int | | 折扣专用库存上限 |
| `--combines` | string | | 允许叠加 |
| `--customer-segments` | string | | 限定客户群 |
| `--name` | string | | 活动名称 |
| `--start` | string | | 开始时间（默认：`now`） |
| `--end` | string | | 结束时间（默认：`-1`） |

```shell
# 全场 8 折
shoplazza discounts +flashsale --value 20

# 指定变体定价 19.99
shoplazza discounts +flashsale --value 19.99 --type fixed-price --variants "v1,v2"

# 带库存限制
shoplazza discounts +flashsale --value 30 --stock 100 --limit-user-variant 2
```

### +mn-discount

创建第 N 件折扣（买 M 件第 N 件打折）。

```shell
shoplazza discounts +mn-discount [flags]
```

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `--tiers` | string | 是 | `N:percent` 对（如 `2:30,3:50`：买 2 件第 2 件 7 折，买 3 件第 3 件 5 折） |
| `--scope` | string | | 应用层级：`highest`、`all`、`highest-all`（默认：`highest`） |
| `--products` | string | | 商品 ID |
| `--collections` | string | | 集合 ID |
| `--variants` | string | | 变体 ID |
| `--exclude` | bool | | 将 ID 作为排除列表（默认：`false`） |
| `--price-sort` | string | | 价格排序方向：`desc`（高→低）或 `asc`（默认：`desc`） |
| `--combines` | string | | 允许叠加 |
| `--limit-max` | int | | 最大总使用次数 |
| `--limit-user` | int | | 每用户最大使用次数 |
| `--customer-segments` | string | | 限定客户群 |
| `--name` | string | | 活动名称 |
| `--start` | string | | 开始时间（默认：`now`） |
| `--end` | string | | 结束时间（默认：`-1`） |

```shell
shoplazza discounts +mn-discount --tiers "2:30,3:50"
shoplazza discounts +mn-discount --tiers "3:50" --products "id1,id2"
```

### +percent-code

创建百分比折扣码。

```shell
shoplazza discounts +percent-code [flags]
```

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `--target` | string | 是 | 范围：`order` 或 `product` |
| `--percent` | float | 是 | 折扣百分比（1–99） |
| `--products` | string | | 商品 ID（`--target product` 时 `--products`/`--variants`/`--collections` 必须提供其一） |
| `--variants` | string | | 变体 ID |
| `--collections` | string | | 集合 ID |
| `--exclude` | bool | | 将 ID 作为排除列表 |
| `--min-amount` | float | | 最低订单金额（`target=order`） |
| `--min-quantity` | int | | 最少商品数量（`target=product`，默认：`1`） |
| `--code` | string | | 折扣码（不填则自动生成） |
| `--combines` | string | | 允许叠加 |
| `--limit-max` | int | | 最大总使用次数 |
| `--limit-user` | int | | 每用户最大使用次数 |
| `--customer-segments` | string | | 限定客户群 |
| `--name` | string | | 活动名称 |
| `--start` | string | | 开始时间（默认：`now`） |
| `--end` | string | | 结束时间（默认：`-1`） |

```shell
# 订单级 8 折
shoplazza discounts +percent-code --target order --percent 20

# 自定义折扣码
shoplazza discounts +percent-code --target order --percent 10 --code SAVE10 \
  --min-amount 50 --limit-max 500 --limit-user 1
```

### +amount-code

创建固定金额折扣码。

```shell
shoplazza discounts +amount-code [flags]
```

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `--target` | string | 是 | 范围：`order` 或 `product` |
| `--off` | float | 是 | 固定减免金额 |
| `--products` | string | | 商品 ID（`--target product` 时 `--products`/`--variants`/`--collections` 必须提供其一） |
| `--variants` | string | | 变体 ID |
| `--collections` | string | | 集合 ID |
| `--exclude` | bool | | 将 ID 作为排除列表 |
| `--min-amount` | float | | 最低订单金额 |
| `--min-quantity` | int | | 最少商品数量（默认：`1`） |
| `--limit-order-once` | bool | | 每单最多应用一次（默认：`true`） |
| `--code` | string | | 折扣码 |
| `--combines` | string | | 允许叠加 |
| `--limit-max` | int | | 最大总使用次数 |
| `--limit-user` | int | | 每用户最大使用次数 |
| `--customer-segments` | string | | 限定客户群 |
| `--name` | string | | 活动名称 |
| `--start` | string | | 开始时间（默认：`now`） |
| `--end` | string | | 结束时间（默认：`-1`） |

```shell
shoplazza discounts +amount-code --target order --off 10
shoplazza discounts +amount-code --target order --off 20 --code OFF20 --min-amount 100
```

### +bxgy-code

创建买 X 送 Y 折扣码。

```shell
shoplazza discounts +bxgy-code [flags]
```

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `--products` | string | | 购买侧商品 ID（`--products`/`--variants`/`--collections` 必须提供其一） |
| `--variants` | string | | 购买侧变体 ID |
| `--collections` | string | | 购买侧集合 ID |
| `--exclude` | bool | | 购买侧 ID 作为排除列表 |
| `--buy-quantity` | int | | 触发所需总件数（`--buy-quantity`/`--buy-amount` 必须且只能提供其一） |
| `--buy-amount` | float | | 触发所需总金额（与 `--buy-quantity` 互斥） |
| `--get-products` | string | | 赠品侧商品 ID（`--get-products`/`--get-variants`/`--get-collections` 必须提供其一） |
| `--get-variants` | string | | 赠品侧变体 ID |
| `--get-collections` | string | | 赠品侧集合 ID |
| `--get-quantity` | int | 是 | 赠品数量 |
| `--get-percent` | int | | 赠品折扣百分比（1–99；percent/off/free 三选一） |
| `--get-off` | float | | 赠品固定减免 |
| `--get-free` | bool | | 赠品免费 |
| `--code` | string | | 折扣码 |
| `--limit-order` | int | | 每单最多应用次数（默认：`1`，`-1` 为无限） |
| `--combines` | string | | 允许叠加 |
| `--limit-max` | int | | 最大总使用次数 |
| `--limit-user` | int | | 每用户最大使用次数 |
| `--customer-segments` | string | | 限定客户群 |
| `--name` | string | | 活动名称 |
| `--start` | string | | 开始时间（默认：`now`） |
| `--end` | string | | 结束时间（默认：`-1`） |

```shell
# 买 3 件 A 商品，送 1 件 B 商品
shoplazza discounts +bxgy-code --products "prodA" --buy-quantity 3 \
  --get-products "prodB" --get-quantity 1 --get-free
```

### +free-shipping-code

创建包邮折扣码。

```shell
shoplazza discounts +free-shipping-code [flags]
```

| 参数 | 类型 | 说明 |
|------|------|------|
| `--off` | float | 运费减免金额（不填为全额包邮） |
| `--min-amount` | float | 最低订单金额（与 `--min-quantity` 互斥） |
| `--min-quantity` | int | 最少商品数量（与 `--min-amount` 互斥） |
| `--countries` | string | ISO 国家代码（逗号分隔）或 `all` |
| `--code` | string | 折扣码 |
| `--combines` | string | 允许叠加 |
| `--limit-max` | int | 最大总使用次数 |
| `--limit-user` | int | 每用户最大使用次数 |
| `--customer-segments` | string | 限定客户群 |
| `--name` | string | 活动名称 |
| `--start` | string | 开始时间（默认：`now`） |
| `--end` | string | 结束时间（默认：`-1`） |

```shell
# 全额包邮
shoplazza discounts +free-shipping-code

# 满 100 包邮
shoplazza discounts +free-shipping-code --min-amount 100

# 指定国家
shoplazza discounts +free-shipping-code --countries US,CA --code FREESHIP
```

## API 命令

所有动态 API 命令共享以下参数：

| 参数 | 短参 | 说明 |
|------|------|------|
| `--params` | | 路径/查询参数（JSON 格式） |
| `--data` | | 请求体（JSON 格式，可内联、`@file` 或 `-` 读取 stdin）；仅在需要请求体的命令上提供 |
| `--jq` | `-q` | jq 表达式过滤输出 |
| `--dry-run` | | 预览请求，不实际执行 |

### discounts

```shell
shoplazza discounts list
shoplazza discounts get --params '{"id":"123"}'
shoplazza discounts create-automatic --data @discount.json
shoplazza discounts create-non-automatic --data @discount.json
shoplazza discounts update-automatic --params '{"id":"123"}' --data @discount.json
shoplazza discounts update-non-automatic --params '{"id":"123"}' --data @discount.json
shoplazza discounts delete --params '{"id":"123"}'
shoplazza discounts batch-delete --data '{"ids":["123","456"]}'
shoplazza discounts get-by-code --params '{"discount_code":"SALE20"}'
shoplazza discounts cancel --data '{"ids":["123"]}'
shoplazza discounts restart --data '{"id":"123"}'
shoplazza discounts combine --data @combine.json
```

### discounts coupons

```shell
shoplazza discounts coupons create --data @coupon.json
shoplazza discounts coupons get --params '{"id":"123"}'
shoplazza discounts coupons update --params '{"id":"123"}' --data @coupon.json
```

## Schema 自省

```shell
shoplazza schema discounts
shoplazza schema discounts.create-automatic
```