> ## Documentation Index
> Fetch the complete documentation index at: https://docs.waffo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 促销码端点

> 为优惠券发放更多的码，每个码可以有自己的限制

促销码是买家可以为某张已有[优惠券](https://docs.waffo.ai/zh/api-reference/endpoints/coupons/overview.md)输入的另一个码。它享受该优惠券的优惠。优惠券只限制到期时间与总使用次数，买家限制设置在每个促销码上。适合给某位达人、某个推广渠道单独发码，或批量生成一次性码。

只能为 `active` 的优惠券创建促销码，促销码与优惠券属于同一店铺、同一环境。创建促销码不会改变优惠券的优惠内容。

## 促销码状态值

| 状态 | 说明 |
| - | - |
| `active` | 所属优惠券为 `active` 时可在收银台使用 |
| `inactive` | 已停用。停用不可恢复，无法重新启用 |

## 附加限制

每个促销码有各自的买家限制；优惠券的 `redeemBy` 与 `maxRedemptions` 同样对每个码生效：

| 字段 | 说明 |
| - | - |
| `customerEmails` | 仅限这些买家（最多 100 个邮箱，不区分大小写） |
| `perCustomerLimit` | 每个买家的累计使用次数 |
| `maxRedemptions` | 本促销码的使用次数。不能超过优惠券的 `maxRedemptions`，优惠券的上限同时生效 |
| `expiresAt` | 到期时间。不能晚于优惠券的 `redeemBy`；不传时取优惠券的 `redeemBy` |
| `minimumAmount` | 按币种的最低消费，按优惠前、不含税的金额判断，例如 `{ "USD": "50.00" }`。未列出的币种不设门槛 |

促销码可以在创建优惠券时一并创建（[创建优惠券](https://docs.waffo.ai/zh/api-reference/endpoints/coupons/create-coupon.md)，最多 20 个），也可以用下面的端点单个或批量创建。优惠券自己的 `code` 不属于它的促销码：它没有自己的限制，`promotionCodes` 不返回它，只能随优惠券一起停用。

## 码

促销码与优惠券使用同一套[码格式](https://docs.waffo.ai/zh/api-reference/endpoints/coupons/overview.md)：3–32 个字母、数字或 `-`，不区分大小写，以大写存储，在同一店铺、同一环境的有效码中唯一，停用后释放。不传 `code` 或批量生成时，随机部分由大写字母和数字组成，并去掉了容易混淆的 `0`、`O`、`1`、`I`、`L`。

## 安全重试

请带上 `X-Idempotency-Key` 请求头（SDK 中为 `idempotencyKey` 选项），重试时沿用同一个键。这对[批量生成促销码](https://docs.waffo.ai/zh/api-reference/endpoints/promotion-codes/generate-promotion-codes.md)尤其重要：码是随机生成的，不带键重试会再生成一批。幂等键的要求见[错误处理](https://docs.waffo.ai/zh/api-reference/errors.md)。

## 读取促销码

这些端点只负责写入。优惠券下的促销码请用 [GraphQL](https://docs.waffo.ai/zh/api-reference/endpoints/graphql/overview.md) 的 `promotionCodes` 和 `promotionCodesCount` 查询；按 `batchId` 过滤可重新读取某一批生成的码。

```graphql theme={"system"}
query PromotionCodes($couponId: String!) {
  promotionCodes(couponId: $couponId, limit: 50, offset: 0) {
    id
    code
    status
    batchId
    timesRedeemed
  }
  promotionCodesCount(couponId: $couponId)
}
```

## 端点

> **[创建促销码](https://docs.waffo.ai/zh/api-reference/endpoints/promotion-codes/create-promotion-code.md)**
>
> 为优惠券新增一个促销码。

> **[批量生成促销码](https://docs.waffo.ai/zh/api-reference/endpoints/promotion-codes/generate-promotion-codes.md)**
>
> 一次生成 1–500 个随机促销码。

> **[停用促销码](https://docs.waffo.ai/zh/api-reference/endpoints/promotion-codes/deactivate-promotion-code.md)**
>
> 永久停用促销码并释放它的码。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.