> ## 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.
# 通知收件人端点
> 管理门店商户通知邮件的收件人
商户通知 —— 新订单、新订阅、续费、取消、逾期 —— 投递到门店配置的收件人。每个收件人拥有各自的地址与各自的逐事件订阅开关，因此同一门店下的两个人可以订阅不同的事件。门店未配置任何收件人时，通知回退到门店 owner 的账号邮箱。
## 事件目录
| 开关 | 触发时机 |
| ------------------------------- | --------------------- |
| `notifyNewOrders` | 产生新的一次性订单（同时覆盖首单庆祝邮件） |
| `notifyNewSubscriptions` | 新订阅激活 |
| `notifySubscriptionCanceled` | 订阅被取消，但访问期仍在进行 |
| `notifySubscriptionRenewed` | 订阅续费扣款成功 |
| `notifySubscriptionEnded` | 订阅彻底结束，访问权被收回 |
| `notifySubscriptionPastDue` | 订阅续费失败，进入逾期 |
| `notifySubscriptionUncanceled` | 订阅撤销了待生效的取消 |
| `notifySubscriptionPlanChanged` | 订阅换方案生效 |
| `notifyChargeback` | 支付被持卡人发起拒付 |
上表 9 个开关**全部是逐收件人**的 —— 包括 `notifySubscriptionPlanChanged` 与 `notifyChargeback`。同一门店下的两个人可以订阅不同的事件，`update-recipient` 接受这 9 个键中的任意一个。
投递**地址**跟收件人列表走：商户通知发到已配置的收件人（列表为空时回退 owner 账号邮箱），不再发到 `supportEmail`。
## 限制
每个门店最多 **5 个收件人**，超出上限返回 400。没有下限 —— 但空列表不等于静默：它会回退到门店 owner 的账号邮箱（见下节）。面向消费者的交易邮件（订单收据、订阅确认）是另一条链路，不受影响。
## 兜底收件人
门店没有显式收件人时，列表里恰好有一条 `isPrimary: true` 的合成条目：地址是门店 owner 的账号邮箱，开关取门店级的 `notify*`，`createdAt` 取门店创建时间。它的 `id` 是形如 `OWNER_` 的稳定哨兵值。
它**不是存储里的一行**。对该 id 调用 `remove-recipient` 返回 404 —— 账号邮箱是兜底，不可删除；要取代它就添加一个真实收件人。对该 id 调用 `update-recipient` 则会**就地物化**：账号邮箱被写成一条真实收件人，你的 patch 叠加其上，响应返回真实 UUID。
添加第一个显式收件人后，兜底条目随即消失。这是有意的可见行为。
## 环境
收件人**不分环境**。请求可以照常携带 `X-Environment`，但它不参与收件人读写的过滤与改写 —— 同一门店在 `test` 与 `prod` 下返回同一份列表。
## 列出收件人
没有 `list-recipients` 端点 —— 查询收件人列表走 GraphQL 顶层查询 `storeNotificationRecipients`；未配置显式收件人时，它同样返回那条兜底条目：
```graphql theme={"system"}
query GetStoreNotificationRecipients($storeId: String!) {
storeNotificationRecipients(storeId: $storeId, limit: 10, offset: 0) {
id
email
isPrimary
createdAt
preferences {
notifyNewOrders
notifyNewSubscriptions
notifySubscriptionCanceled
notifySubscriptionRenewed
notifySubscriptionEnded
notifySubscriptionPastDue
notifySubscriptionUncanceled
notifySubscriptionPlanChanged
notifyChargeback
}
}
}
```
## 端点
添加一个接收商户通知的地址。
修改收件人订阅的事件。
从列表中移除一个收件人。