> ## Documentation Index > Fetch the complete documentation index at: https://waffo.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # 优惠券与促销码 > Waffo 折扣引擎全流程：按百分比与按固定金额的优惠券、Once / Repeating / Forever 持续周期、单个与批量促销码、核销记录、折扣分析、账户级上限、订阅试用、退款回滚，以及两个 API 入口。 Waffo 自带一套折扣引擎。你定义**优惠券**（折扣是什么），并发放**促销码**（客户输入的字符串，或由你分发），然后在 Portal 中读取核销记录和折扣支出。这些都在 **Marketing** 菜单下：Coupons、Promotion Codes、Discount Analytics 和 Coupon Settings。该功能受权限控制——如果你的 Portal 中能看到 Marketing 菜单，说明你的账户已开通。 ## 如何定义折扣本身？ | 折扣类型 | 你配置的内容 | 应用方式 | | - | - | - | | `PERCENT_OFF` | 一个整数百分比，1–100 | 适用于任何币种。100 表示订单免费 | | `AMOUNT_OFF` | **按币种**设置的固定金额 | 仅适用于你配置了的币种 | `AMOUNT_OFF` 优惠券中未配置的币种**不**符合条件——该币种的订单会被拒绝，而不是悄悄按全价收费。请配置你销售的每一个币种。 持续周期按**账单周期**计数，因此只对订阅有影响；一次性支付无论如何都只消耗一次折扣。`ONCE`——仅一次支付，对同一折扣的第二次尝试会被拒绝。`REPEATING`——N 个周期，同时还要设置 **Duration in Cycles**。`FOREVER`——每个周期。 ## 创建优惠券时还要填哪些内容？ | 字段 | 值得了解的规则 | | - | - | | **Coupon Name** | 面向客户，显示在发票和收据上。最多 40 个字符 | | **Max Redemptions** | 该优惠券下**所有**促销码的总核销次数。请提供一个值——创建请求要求填写 | | **Daily Redemption Limit** | 可选。按**客户**、按天计。需要支付上带有客户标识 | | **Expiry Date**（`redeemBy`） | 可选。超过该时间后优惠券不再能核销 | | **Category Tags**（`appliesTo`） | 可选。仅 `goodsCategory` 匹配的订单符合条件；为空表示全部 | | **Metadata** | 供你自己跟踪用的自由键值对，不向客户展示 | 折扣类型、折扣值和持续周期**创建后不可更改**——页面会在你提交前提示，之后只有 **Name** 和 **Metadata** 可编辑。**Deactivate** 停止后续核销，且可逆；**Archive** 不可逆，并同时停用该优惠券的促销码。两者都不影响已应用的折扣。列表显示的是生命周期标签而不是原始状态：已归档优先，其次是已过期（超过 `redeemBy`），再是优惠券自身的状态。 ## 如何发放促销码？ | | 单个码 | 批量 | | - | - | - | | 码字符串 | 由你输入。仅限字母数字，自动转大写，在你的账户内唯一，**之后不可编辑** | 由**前缀**（字母数字，最多 10 个字符）生成，例如 `BFK2X9P`、`BFM7L3Q` | | 数量 | 1 | 每批 1–10,000 | | 限制条件 | 该码的 Max Redemptions、有效期、First Time Only、按币种的 Minimum Amount | 同一组限制，应用于批次中的每个码 | 批量创建是一个四步向导——选择优惠券、设置前缀和数量、设置限制条件，然后在提交前有一个**预览**，返回示例码和预计生成时间。生成的码是永久的，所以请先规划好前缀和数量。批量任务异步执行：**Batch Tasks** 列出 Task ID、优惠券、状态（`PENDING` → `PROCESSING` → `SUCCESS` / `FAILED`）、成功数量和创建时间，并可跳转到该任务生成的码。码级别的有效期不能延长优惠券的有效期——优惠券自身的 `redeemBy` 仍会单独校验，因此两者中较早的一个决定核销截止。 ## 为什么在收银台输入的码被拒绝了？ 资格判断在金额计算之前，大致按以下顺序： * 你的账户**已禁用优惠券**，或尚不存在任何优惠券配置。 * 优惠券或码处于停用、已过期状态，或核销库存已耗尽；或该码不属于同一请求中传入的优惠券。 * 订单金额低于该码在该币种下的 **Minimum Amount**，或 `AMOUNT_OFF` 未为订单币种配置金额。 * 适用按客户限制、每日限制或 **First Time Only**，但请求中**没有客户标识**——折扣会被拒绝，而不是不受限制地应用。 * **First Time Only** 且该客户已有一次已完成的核销——范围是你的整个账户，而不是这一张优惠券。 * `ONCE` 优惠券已被使用，或 `REPEATING` 优惠券已用完其周期数。 ## 我在哪里能看到谁核销了什么？ 优惠券详情页有 Overview、Promotion Codes 和 **Redemption History** 三个标签页。每条核销记录包含 Record ID、促销码、客户、来源类型和来源 ID、订单币种下的 **Original / Discount / Final** 金额、状态和创建时间。可按客户、来源 ID、状态和日期范围筛选，然后导出筛选后的视图。状态流转为 `CREATED`（已预留，尚未最终确定）→ `COMPLETED`（已确认——分析只统计这一种状态），或 `VOIDED`（支付从未完成，预留已释放）/ `REVERSED`（退款后已回滚）。 ## Discount Analytics 是怎么计算的？ 三个注意点决定了数字是否与你自己的对得上。它**只统计已完成的核销**，因此 `CREATED`、`VOIDED` 和 `REVERSED` 被排除。金额**跨币种直接相加、不做换算**，这也是为什么卡片和表现表格显示的是不带币种符号的裸数字——需要按币种合计请使用核销记录导出。并且 **Redemption Rate** = 已完成核销数 ÷ 范围内优惠券的 Max Redemptions 之和，因此没有上限的优惠券对分母贡献为 0。 默认范围为最近 30 天。趋势图按每次核销的**确认**时间在你的 Portal 时区分桶，Daily / Weekly / Monthly 切换对同一数据重新分桶。Coupon Performance 按优惠券拆分该周期：Total Codes、Redemptions、Total Discount、Redemption Rate、Average Order Value。 ## 账户级的优惠券设置有什么作用？ | 设置 | 效果 | | - | - | | **Enable Coupons** | 总开关。关闭后拒绝所有折扣请求，无论优惠券怎么配置 | | **Coupon Scope** | `SELF_ONLY` 或 `PLATFORM_WIDE`——折扣是否只限于你自己的商户范围 | | **Max Active Coupons** | 账户记录的同时生效优惠券数量上限 | | **Max Discount Percent** | 在核销时对 `PERCENT_OFF` 设上限：实际生效的百分比取优惠券值与该上限中**较低者**。50% 上限下的 60% 优惠券折 50%——静默限制，不会拒绝 | | **Refund Reversal Strategy** | 见下文 | ## 退款时折扣会怎样，订阅试用期间又如何？ 在 **Full Reversal** 策略下，**全额退款**会回滚核销——记录变为 `REVERSED`，名额同时归还给优惠券和促销码。**部分退款**则**不会**回滚：记录保持 `COMPLETED`，名额仍被占用。从未完成的支付则以 `VOIDED` 释放预留。回滚只归还实际消耗的部分，因此一个从未获得真实折扣的周期不会把计数器推成负数。 零金额的试用期会**占用该周期在优惠券和促销码上的核销名额**，但**不会**消耗折扣自身的生命周期计数。因此，带免费试用的订阅上的 `ONCE` 优惠券，其唯一一次真实折扣仍可用于首个付费周期。订阅之外，未实际应用折扣的零金额订单不消耗任何东西。 ## 如何通过 API 应用折扣？ 创建订单时携带一个 `promotionInfo` 对象，包含两个互斥字段，各最长 64 个字符。`promotionInfo.promotionCode` 由你或 Waffo 托管的收银台页面使用——收银台的折扣输入框**只接受促销码**，因此客户永远无法输入优惠券 ID。`promotionInfo.couponId` 只归你使用，在创建订单时应用某张特定优惠券而不涉及任何码。二者只传其一，切勿同时传；如果码和优惠券 ID 同时到达，该码必须属于该优惠券。创建订单的字段级规则以及收银台页面自身的行为，见创建订单字段指南和收银台页面文档。 ## 我能从 Marketing 页面导出什么？ Marketing 页面管理的一切都是 Portal 功能——创建、编辑、停用和归档优惠券；创建单个码和码批次；浏览核销记录和分析——其中任何一项都没有 API-key 签名的集成接口。唯一的 API 触点是上文创建订单时的 `promotionInfo`。 四个列表有 **Export** 按钮：Coupons、Promotion Codes、Redemption History 和 Discount Analytics。每次导出作为一个任务运行，并给你一个名为 `-.csv` 的 CSV——前缀为 `coupon`、`promotion-code`、`promotion-record` 或 `promotion-analytics`。导出遵循屏幕上的筛选条件，最多覆盖 10,000 行。列表和导出中的时间戳按你的 Portal 时区渲染；Portal 会随请求发送其时区偏移。 *** 数字对不上？请[联系支持](mailto:support@waffo.com)，并附上优惠券 ID、促销码或核销 Record ID。 This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.