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

# 订阅

> 自动化的经常性收入

## 经常性收入，自动化管理。

客户订阅后，我们处理计费周期、续费重试和生命周期管理。你专注于产品即可。

***

## 工作原理

```
客户订阅 → 计费周期 → 自动扣款 → 循环
```

如果续费扣款未成功，订阅会进入 `past_due` 状态。这个状态表示订阅进入续费恢复阶段，而不是立即失效；系统会在宽限期内继续重试或等待用户更新支付方式。

***

## 订阅套餐如何建模

在 Waffo Pancake 中，**每一个可单独购买的订阅选项** 都是一个独立的订阅产品。

最常见的区分方式是计费周期，例如：

* 月付
* 年付

如果你同时提供月付和年付，通常应建模为 **2 个订阅产品**。

| 业务展示方式 | 在 Waffo 中的建模方式 |
| ------ | -------------- |
| 月付方案   | 1 个订阅产品        |
| 年付方案   | 1 个订阅产品        |

***

## 订阅状态

| 状态          | 说明                  |
| ----------- | ------------------- |
| `pending`   | 等待首次付款              |
| `active`    | 正常运行，正常计费           |
| `trialing`  | 免费试用期               |
| `past_due`  | 续费扣款未成功，处于恢复/宽限阶段   |
| `canceling` | 已请求取消，在当前周期结束前仍保持活跃 |
| `canceled`  | 当前周期结束后不再续费         |
| `expired`   | 订阅已过期               |
| `closed`    | 从未激活 — 支付超时         |

***

## 计费周期

| 周期  | 频率      | 最适用于    |
| --- | ------- | ------- |
| 每周  | 每 7 天   | 高使用量产品  |
| 每月  | 每月      | 标准 SaaS |
| 每季度 | 每 3 个月  | B2B 软件  |
| 每年  | 每 12 个月 | 长期客户    |

***

## 免费试用

降低注册门槛，让客户先试用再购买。

### 配置试用

创建订阅产品时，在控制台中启用试用开关并设置试用天数。

### 平台级试用保护

Waffo Pancake 作为 Merchant of Record（MoR），会在平台层自动防止试用被重复滥用：

| 层级      | 运作方式                                                     |
| ------- | -------------------------------------------------------- |
| **平台层** | 跨所有商户追踪消费者的试用历史，并为每次新订阅计算可用的最大试用天数。                      |
| **商户侧** | 可在通过 API 创建订单时传递 `requested_trial_days`，按客户缩短试用期或直接跳过试用。 |

**两个层级如何交互：**

* 如果商户请求 ≤ 平台最大值 → 使用商户请求的值
* 如果商户请求 > 平台最大值 → 回退到平台最大值
* 如果商户未指定 → 使用完整的平台最大值

### 买家身份与试用保护

试用资格通过 `buyerIdentity` 追踪 — 您通过[认证式收银台](/zh/integrate/sdks#收银台模式)提供的稳定标识符。平台使用此标识检测跨会话的重复试用领取。

<Warning>
  不提供 `buyerIdentity`（匿名收银台）时，试用资格检查将被完全跳过。买家可以通过更换邮箱地址无限领取试用。
</Warning>

<Tip>
  7-14 天的试用效果最佳。太短 = 没有足够时间评估。太长 = 容易被遗忘。
</Tip>

***

## 续费恢复

当续费扣款未成功时，订阅会转为 `past_due` 状态。这个状态通常意味着系统正在等待支付方式更新，或处于重试与恢复窗口中，而不是立刻终止服务。

常见处理方式：

* 系统通知客户更新支付方式
* 在一定宽限期内保留访问权限
* 后续按重试策略继续尝试扣款

<Note>
  `past_due` 更适合理解为“续费异常待恢复”，而不是“付款失败后立即终止”。
</Note>

***

## 管理订阅

### 取消

取消时，订阅会先进入 `canceling` 中间状态，在当前计费周期结束时自动转为 `canceled`。客户在此期间保留访问权限。

```bash theme={"system"}
POST /v1/actions/subscription-order/cancel-order
{
  "orderId": "ORD_5dXBtmF2HLlHfbPNm0Wcnz"
}
```

响应中返回 `canceling` 状态，表示订阅将在当前周期结束后正式取消。

<Note>
  没有立即取消的选项。客户始终保留访问权限直到已付费周期结束。取消后状态流转为：`active` → `canceling` → `canceled`。
</Note>

### 恢复订阅

如果订阅仍处于 `canceling` 状态，客户可以在当前周期结束前恢复订阅。

恢复后：

* 订阅状态回到 `active`
* 当前周期内的访问权限保持不变
* 后续将按原有周期继续正常续费

<Note>
  恢复订阅适用于“已经请求取消，但尚未到期”的场景。本质上是撤销取消操作，而不是重新购买一个新订阅。
</Note>

### 升级/降级

| 场景    | 行为           |
| ----- | ------------ |
| 周期中升级 | 立即生效         |
| 周期中降级 | 在当前计费周期结束时生效 |

```bash theme={"system"}
POST /v1/actions/subscription-order/change-product
{
  "orderId": "550e8400-e29b-41d4-a716-446655440000",
  "targetProductId": "target-product-uuid"
}
```

<Warning>
  此端点尚未实现（返回 501）。将在未来版本中提供。
</Warning>

## 指标

### MRR（月经常性收入）

```
周订阅：    $10 × 4.33 = $43.30 MRR
月订阅：    $29 × 1 = $29 MRR
年订阅：    $290 ÷ 12 = $24.17 MRR
```

### 关键指标

| 指标    | 含义       |
| ----- | -------- |
| MRR   | 月经常性收入   |
| Churn | 取消订阅的百分比 |
| LTV   | 客户终身价值   |
| ARPU  | 每用户平均收入  |

***

## Webhooks

通过 Webhook 订阅订阅生命周期事件。在 **设置 → Webhook** 中配置端点。

<Warning>
  此处不列出具体的 Webhook 事件名称，因为它们可能会变更。请参阅控制台中的 Webhook 配置以获取当前可用事件列表。
</Warning>

Webhook 负载遵循 Waffo Pancake 的标准约定：

* ID 为 UUID v4 格式
* 金额以显示格式字符串表示
* 时间戳为 ISO 8601 UTC 格式
* 计费频率使用 `billingPeriod` 字段（例如 `monthly`、`yearly`）

***

## 客户门户

让客户自助管理订阅：

* 查看详情
* 更新支付方式
* 更换方案
* 取消
* 恢复订阅
* 下载发票

<Card title="客户门户" icon="user" href="/zh/merchant/customer-portal">
  自助式订阅管理。
</Card>

***

## 最佳实践

<AccordionGroup>
  <Accordion title="提供年付折扣">
    年付优惠 15-20% = 降低流失率 + 改善现金流。
  </Accordion>

  <Accordion title="不要立即中断访问">
    续费未成功 ≠ 立即取消。给客户时间更新支付方式并完成恢复。
  </Accordion>

  <Accordion title="发送提醒">
    试用即将到期、即将扣款。不要让客户感到意外。
  </Accordion>
</AccordionGroup>