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

# 优惠券端点

> 创建和管理优惠券，以及买家在收银台输入的码

优惠券定义一项优惠：按百分比减免，或按币种减免固定金额，并规定对订阅生效几个计费周期。每张优惠券都有自己的 `code`（创建时填写，或由 Pancake 生成），买家可在收银台输入它。如果想为同一项优惠发放更多的码，请创建[促销码](https://docs.waffo.ai/zh/api-reference/endpoints/promotion-codes/overview.md) —— 创建优惠券时可同时创建最多 20 个，之后也可随时补充。优惠券也可在结账会话上按 ID（`couponId`）使用。优惠券只限制到期时间与总使用次数；买家限制 —— 限定买家邮箱、每位买家次数与最低消费 —— 设置在促销码上，因此优惠券自己的码没有这些限制。

优惠券归属于店铺，并且只存在于一个环境：在 `test` 创建的优惠券在 `prod` 中不存在，反之亦然。

## 优惠券状态值

| 状态 | 说明 |
| - | - |
| `active` | 可在收银台使用 |
| `inactive` | 已停用。停用不可恢复，无法重新启用 |
| `failed` | 创建失败：支付服务商拒绝了该优惠券，或未确认创建。本次请求的码已全部释放。请重新创建优惠券 —— 可以继续使用同样的码 |

## 优惠规则

| 规则 | 字段 | 说明 |
| - | - | - |
| 优惠方式 | `discount` | `percentage`（`percentOff`，0 \< x ≤ 100，最多 2 位小数）或 `fixed_amount`（按币种给出 `amountOff`）。订单币种不在 `amountOff` 中时不能使用该优惠券，不做汇率换算 |
| 订阅生效周期 | `duration`、`durationInPeriods` | `once`（默认）、`repeating`（生效 `durationInPeriods` 个计费周期）或 `forever`。一次性订单只优惠一次 |
| 适用商品 | `productIds` | 仅对这些商品生效。为空或不传表示全店通用 |
| 到期时间 | `redeemBy` | 过了这个时间优惠券不能再使用，已挂在订阅上的优惠也一并结束 |
| 总使用次数 | `maxRedemptions` | 优惠券的码与全部促销码合计的总兑换上限。退款不会退回次数 |

创建后只能修改 `name`。要调整优惠内容，请新建一张优惠券，并停用旧的。

## 码格式

优惠券的码和促销码使用同一套规则：

| 规则 | 说明 |
| - | - |
| 字符 | 字母、数字和 `-`。不允许空格、`_` 或其他符号 |
| 长度 | 3–32 个字符 |
| 大小写 | 不区分大小写。码统一以大写存储和返回（`bf2026` 会变成 `BF2026`） |
| 唯一性 | 在同一店铺、同一环境的**有效**码中唯一，优惠券与促销码共用这一范围 |
| 复用 | 停用优惠券或促销码会立即释放其码，之后新的优惠券或促销码可以使用这些码 |

## 停用

停用是**不可恢复**的：没有重新启用，也没有删除。停用优惠券时，它下面的所有促销码也会一并停用并释放各自的码。已有订单不受影响；已挂在订阅上的优惠会继续生效，直到该订阅下一次更换方案。

## 安全重试

创建优惠券时请带上 `X-Idempotency-Key` 请求头（SDK 中为 `idempotencyKey` 选项），重试时沿用同一个键。如果不带键，只有指定了码（`code` 或 `promotionCodes[].code`）时，超时后的重试才会返回 `409`：第一次请求其实已经创建了优惠券并占用了这些码。由 Pancake 随机生成码时，重试会再创建一张优惠券。幂等键的要求见[错误处理](https://docs.waffo.ai/zh/api-reference/errors.md)。

## 读取优惠券

这些端点只负责写入。列表和详情请用 [GraphQL](https://docs.waffo.ai/zh/api-reference/endpoints/graphql/overview.md) 查询：优惠券用 `coupons`、`couponsCount` 和 `coupon(id)`，其促销码用 `promotionCodes` 和 `promotionCodesCount`。

```graphql theme={"system"}
query Coupons($storeId: String!) {
  coupons(storeId: $storeId, limit: 20, offset: 0, filter: { status: { eq: active } }) {
    id
    name
    code
    status
    timesRedeemed
    promotionCodesCount
  }
  couponsCount(storeId: $storeId, filter: { status: { eq: active } })
}
```

## 端点

> **[创建优惠券](https://docs.waffo.ai/zh/api-reference/endpoints/coupons/create-coupon.md)**
>
> 创建优惠券及它的码，并可同时创建它的促销码。

> **[更新优惠券](https://docs.waffo.ai/zh/api-reference/endpoints/coupons/update-coupon.md)**
>
> 修改优惠券名称。

> **[停用优惠券](https://docs.waffo.ai/zh/api-reference/endpoints/coupons/deactivate-coupon.md)**
>
> 永久停用优惠券及其全部促销码。


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