> ## 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 会给我的订阅客户发哪些邮件？

> Waffo 可以直接发给订阅者的六封邮件、每一封确切的触发时机、以哪种语言渲染、如何避免与你自己的邮件重复，以及订阅计费历史返回什么。

Waffo 可以在订阅生命周期的六个节点直接给你的订阅者发邮件。本页讲的是**这些邮件**——什么触发它们，以及如何避免让客户每样东西都收到两份。
Waffo 发给*你的*服务器的Webhook 通知，见[订阅 FAQ](/docs/zh/support/subscription-faq)中的通知表；重试行为见
[订阅重试与支付方式](/docs/zh/support/subscription-retry-and-payment-methods-faq)。

## Waffo 会给我的订阅者发哪些邮件？

六封，每封都有独立的开/关开关——所以你的账户可以启用任意子集：

| 邮件 | 触发时机 |
| - | - |
| 订阅已激活 | 订阅在**第一个**计费期到达 `ACTIVE`。 |
| 试用即将结束 | 试用期结束前不久。 |
| 即将扣款 | 每次扣款前不久，**含试用期**。 |
| 支付失败 | 一次扣款尝试失败——有条件，见下文。 |
| 订阅已取消 | 一次取消完成。 |
| 订阅已变更 | 你通过 update API 修改了金额。 |

第六行是大多数集成会漏掉的。如果你已经在自己给客户发价格变更邮件，请在发送之前确认你的账户是否启用了**订阅已变更**邮件。

## 每一封具体什么时候触发？

六封里有三封是事件驱动的，在事件发生后片刻内送达。两封由每日任务执行，因此落在一个窗口内而不是精确的偏移量。一封由你自己的 API 调用同步触发。

| 邮件 | 机制 | 你可以依赖的时机 |
| - | - | - |
| 订阅已激活 | 事件驱动 | 在转为 `ACTIVE` 时，仅第一期。以零金额授权激活的延迟开始订阅也会收到。 |
| 试用即将结束 | 每日任务 | 一次，在首次发现试用将在其短前瞻窗口（几天）内结束的每日运行中发送。仅当订阅为 `ACTIVE` 且确实处于试用期时发送。 |
| 即将扣款 | 每日任务 | 每期一次，在首次发现下次扣款落入其前瞻窗口（约一天）的每日运行中发送。最后一期不发送。 |
| 支付失败 | 事件驱动 | 见下一节。 |
| 订阅已取消 | 事件驱动 | 取消提交后，对任一取消状态都发送。 |
| 订阅已变更 | 与你的 update 调用同步 | 当一次 update 实际改变了周期金额、试用金额或按期计划金额时。 |

由于两封提醒邮件由**在前瞻窗口上运行的每日任务**驱动，请把它们的偏移量当作近似值。不要在其上构建诸如「您将在恰好 N 小时前收到通知」的对客承诺，
也不要把它们当作你自己排期的时钟。

## 支付失败邮件真的每次失败都会发吗？

不是，而且假设它会发将让你的去重逻辑出错。它在两种情况下被抑制：

* \*\*首期失败不发。\*\*首次扣款就失败的订阅不会给客户产生任何失败邮件。如果你希望此时告知客户，那要由你来做。
* \*\*既非最终尝试、也不属于基于间隔的重试计划的尝试不发。\*\*实际上这意味着立即执行的备用支付方式尝试是静默的；不会每试一张备用卡就给客户发一封邮件。

会发送的情况：每一次独立的计划重试尝试，以及关闭该期的最终尝试。邮件带有一个让客户添加或更新支付方式的链接，这通常正是你希望他们采取的动作。

## 订阅已变更邮件由什么触发，里面有什么？

由你自己对订阅 update API 的调用触发，当它改变了周期金额、试用金额或按期计划金额中的任何一项。它与该调用同步发送，而不是由任务发送。

邮件告诉客户金额原来是多少、现在是多少，以及新金额从哪一期开始适用。如果你修改了按期计划，则会同时包含旧计划和新计划。

值得在设计时考虑的两个后果：

* **套餐变更**（通过 change API 升级/降级）是另一种操作，不会触发这封邮件。见[订阅 FAQ](/docs/zh/support/subscription-faq)中 change/update 的区别。
* 因为触发源是你的 API 调用，对同一订阅快速连续地批量执行多次 update 可能产生多封邮件。每一个你想让客户看到的变更只调用一次 update。

## 这些邮件是什么语言？

收件人的语言按以下顺序解析：

1. 你在订阅上指定的**收银台语言**（如果设置了）。
2. 否则，从订阅的 **`userCurrency`** 推导——即客户实际被扣款的币种。
3. 如果两者都得不出受支持的地区语言，则为英文。

实用规则：\*\*除非你覆盖，否则 `userCurrency` 决定语言。\*\*如果你客户的语言与计费币种不一致——比如一位以本地币种计费的英语客户——
请在订阅上显式设置收银台语言，而不要依赖推导。

同一地区语言也会应用到邮件内的订阅管理链接，所以客户打开的页面语言一致。

## 我能自己编辑模板，或者单独关掉某封邮件吗？

不能从商户 Portal 操作。在当前版本：

* 六个开关**由 Waffo 为你的账户配置**，不是自助的。告诉你的 Waffo 对接人六封中你想开哪些、哪些你更愿意自己负责。
* 模板本身**不可由商户编辑**。会体现的是你的**品牌**——你的商户名称以及你为收银台配置的 logo/外观会应用到邮件上，所以邮件不是无品牌的。

如果你需要自己掌控措辞，正确的做法是让对应的 Waffo 邮件关闭，并用同一事件的Webhook 通知驱动你自己的邮件。

## 怎么避免 Waffo 的邮件和我自己的邮件重复？

对照上表，为每个事件选定一个负责方。可靠的做法：

| 如果你想自己负责 | 那么 |
| - | - |
| 激活/欢迎消息 | 要求关闭激活邮件；用订阅状态通知驱动你自己的邮件。 |
| 续订提醒 | 要求关闭即将扣款邮件；你可以控制偏移量，而每日任务做不到。 |
| 催缴序列 | 要求关闭支付失败邮件；用支付订单通知驱动你自己的邮件，它报告*每一次*尝试，包括邮件抑制的那些。 |
| 价格变更通知 | 要求关闭订阅已变更邮件；你已经知道变更发生了，因为调用是你发起的。 |

不要试图通过把你的邮件卡在 Waffo 邮件前后的时间点来压制它——两封提醒邮件落在一个窗口内，而不是固定的偏移量。

## 每封客户邮件对应哪个Webhook 通知？

每封客户邮件都有一个你可以据以行动的服务端对应物，这正是「关掉邮件、自己发」这一模式可行的原因：

| 客户邮件 | 用什么驱动你自己的邮件 |
| - | - |
| 订阅已激活 | 订阅状态通知，在转为 `ACTIVE` 时。 |
| 试用即将结束 | 你自己根据订阅的试用配置计算的排期——没有按提醒的Webhook 通知。 |
| 即将扣款 | 你自己根据订阅的周期配置计算的排期。 |
| 支付失败 | 订阅支付订单通知，它报告**每一次**尝试——包括邮件抑制的那些。 |
| 订阅已取消 | 订阅状态通知，在任一取消状态时。 |
| 订阅已变更 | `SUBSCRIPTION_UPDATE_NOTIFICATION`，加上你自己 update 调用的响应。 |

两封提醒是没有Webhook 通知对应物的，因为它们是预测而不是事件。如果你想按自己控制的偏移量发提醒，就从订阅本身计算。

## 客户说从没收到邮件，我该查什么？

按这个顺序——前三项覆盖了几乎所有情况：

1. \*\*你的账户开了那个开关吗？\*\*六封都是独立配置且由 Waffo 设置的，所以你以为开着的邮件可能并没有开。这是第一件要确认的事。
2. \*\*是不是被抑制的情况之一？\*\*首期失败不发失败邮件，备用支付方式尝试也不发。首次扣款就失败的客户什么都没收到是正常的。
3. \*\*时机和你假设的一样吗？\*\*两封提醒邮件来自在前瞻窗口上运行的每日任务，所以「没有在我假设的精确偏移量到达」是预期行为，不是邮件丢失。
4. \*\*语言是客户预期的吗？\*\*语言出乎意料的邮件有时会被报告为「没有邮件」。检查订阅的 `userCurrency` 以及你是否设置了收银台语言。
5. \*\*事件本身真的发生了吗？\*\*对照上面对应的Webhook 通知确认——如果订阅从未到达 `ACTIVE`，就不存在要找的激活邮件。

## 订阅计费历史返回什么？

两种不同的视图，选错是常见的集成错误。

**商户查询 API** 返回一组刻意精简的按期字段。在订阅查询上传 `paymentDetails=1` 即可获取：

| 字段 | 含义 |
| - | - |
| `acquiringOrderId` | 该期的订单——你关联交易和退款的键。 |
| `period` | 期号。 |
| `orderCurrency` / `orderAmount` | 以你的定价币种计的金额。 |
| `orderStatus` | 该期的结果。 |
| `orderUpdatedAt` | 该期订单的最后变更时间。 |
| `topupDetails` | 仅出现在有席位加购扣款的期上：该期内发生的加购订单，每条带自己的 `acquiringOrderId`、`topupAmount` 和 `orderStatus`。 |

注意**没有**的内容：没有试用标记、没有用户币种或用户金额、没有期开始/结束日期、没有失败码。如果你需要这些，你需要订单本身——按 `acquiringOrderId` 查询。

你的客户看到的**托管订阅管理页面**渲染更丰富的按期行，包括试用标记、两组币种/金额、期开始和结束、绑定支付方式的掩码卡信息和有效期、
收据链接，以及面向客户的失败原因。该视图是给客户看的；不要把它当作 API 接口。


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