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

# 订阅 FAQ

> 解答关于 Waffo 订阅最常见的问题：升级与降级、金额变更、扣款失败与重试、通知、试用期以及用户侧管理。

本页解答商户关于 Waffo 订阅最常问的问题。字段级契约见
[订阅 API 规范](/docs/api-reference/introduction)。

## 怎么给用户升级或降级套餐？

调用 `/api/v1/subscription/change`。变更请求会**基于原订阅创建一个新订阅**，原订阅的剩余金额会结转到新订阅上——您不需要手动取消再重新创建。

* 通过 `/api/v1/subscription/change/inquiry` 跟踪结果。
* 变更完成时，Waffo 也会推送 `SUBSCRIPTION_CHANGE_NOTIFICATION`。

## `change`、`update` 和 `manage` 有什么区别？

| API | 使用场景 |
| - | - |
| `/api/v1/subscription/change` | 用户切换**套餐**（升级 / 降级）。创建新订阅并结转剩余金额。 |
| `/api/v1/subscription/update` | 您只需要调整现有订阅上的**金额**：周期金额、试用期金额或按期计划金额。不切换套餐，不创建新订阅。 |
| `/api/v1/subscription/manage` | 您想把一个托管页面交给**终端用户**，让其查看或取消自己的订阅。Waffo 返回一个管理 URL，您将用户重定向到该地址；每个 URL 都有自己的过期时间，以 `expiredAt` 返回。 |

金额更新会按您的合同限额校验。

## 不同周期能收不同的金额吗？

可以。两种机制组合起来可以覆盖分级定价和首期优惠：

* **试用期**——创建订阅时设置 `trialPeriodAmount` 和 `numberOfTrialPeriod`。通过 `trialPeriodType` 和 `trialPeriodInterval` 支持自定义试用粒度。
* **计划金额**——为特定的正式周期配置按期金额（例如首期折扣），可在创建时配置，也可之后通过 `/api/v1/subscription/update` 配置。

如果某个周期没有计划金额，则使用订阅的基础 `amount`。

## 扣款失败了，接下来会怎样？

扣款失败会按订阅的重试策略自动重试——您不需要自己触发重试。

* 每一次支付尝试，包括失败原因、时间戳和重试详情，都会通过**订阅支付订单通知**推送。
* 如果您只关心每个计费周期的最终结果，请改为监听 `SUBSCRIPTION_PERIOD_CHANGED_NOTIFICATION`——它每个周期触发一次，携带最终结果，跳过中间的重试事件。

具体的重试计划和上限取决于您合同中配置的重试策略。如需了解您账户的确切策略，请联系集成支持。

## 我应该监听哪些订阅通知？

| 通知 | 层级 | 使用场景 |
| - | - | - |
| 订阅状态通知 | 订阅 | 您需要知道订阅的生命周期状态（已创建、已取消、已过期）。 |
| 订阅支付订单通知 | 支付订单 | 您需要完整了解每一次支付尝试，包括失败和重试。 |
| `SUBSCRIPTION_PERIOD_CHANGED_NOTIFICATION` | 计费周期 | 您只需要每个周期的最终结果。 |
| `SUBSCRIPTION_CHANGE_NOTIFICATION` | 变更请求 | 您需要升级 / 降级的结果。 |
| `SUBSCRIPTION_UPDATE_NOTIFICATION` | 金额更新 | 在 `/api/v1/subscription/update` 成功后发送到订阅的 `notifyUrl`（包括席位加购补款在扣款成功后）。携带与查询 API 返回一致的订阅对象，含新金额。 |

对任何通知，处理完成后请返回 `success`。如果 Waffo 收到 `failed` 或 `unknown`，Waffo 会按分布在接下来一天内的退避计划重试通知；计划详情见[Webhook 通知重试](/docs/zh/developer-docs/webhook/retry)。

## 用户怎么取消订阅？

两条路径：

* **商户发起**——调用 `/api/v1/subscription/cancel`。
* **用户发起**——把用户重定向到通过 `/api/v1/subscription/manage` 获得的托管管理页面，用户可在那里查看详情并取消。
* **钱包侧**——如果用户在钱包 App 内撤销了支付授权，钱包会通知 Waffo。如果被撤销的支付方式是订阅上唯一的一个，订阅会自动取消；如果有备用支付方式，则备用方式成为默认。这会通过订阅状态通知告知您，因此请以Webhook 通知——而不是您自己的记录——作为订阅是否仍然有效的事实来源。

订阅一旦进入已取消状态，就不会再开启新的计费周期。已挂起的重试是否会被立即丢弃取决于您合同中的一项设置——如果这对您重要，请向集成支持确认。

## Waffo 支持按日计费或跨币种订阅吗？

两者都支持：

* `DAILY` 是受支持的 `periodType`，与其他计费周期并列。
* 通过 `userCurrency` 字段支持跨币种订阅——用户以其本地币种支付。

各支付方式的能力和限制列在[订阅 API 规范](/docs/api-reference/introduction)的附录中。

## `subscriptionManagementUrl` 应该传什么？

`subscriptionManagementUrl` 在创建订阅时的文档定义为必填，您应始终传入。请注意，服务端目前**不会**拒绝省略该字段的请求——省略不会以校验错误的形式暴露，而是会在之后以发送到您页面的客户邮件中缺少链接的形式暴露。请将其指向一个用户可以**在桌面浏览器中**打开的页面。App deeplink 在这里是很差的选择：在 PC 上打开的用户可能根本无法访问该页面。您有三个选项：

* 自建带鉴权的订阅管理页面并传入其 URL。
* 用您自己的页面包裹 Waffo 从 `/api/v1/subscription/manage` 返回的托管页面，并传入该页面。
* 直接使用 Waffo 的托管管理页面。

该页面是一个**功能入口，不是支付流程中的一步**。它不会在实时交易中展示；您应在订阅支付成功后展示它——在用户的账户区、订单确认页，或您站点上任何合适的位置。

## 我收到了订阅通知，但马上查询却显示订阅不是 `ACTIVE`

订阅状态是**最终一致**的。通知到达时，内部状态更新可能仍在落地，因此紧接着发起的查询可能返回尚未 `ACTIVE` 的状态。这是读取时机的问题，不是订阅失败。

请这样处理：

* 不要把第一次查询结果当作最终结果。稍作等待后重新查询。
* 优先以订阅状态通知作为状态变化的触发器，用查询来确认而不是决策。

## 试用期金额可以和常规金额一样吗？

不可以。创建时 `trialPeriodAmount` 必须**严格小于** `amount`；相等的值会被拒绝，返回参数错误，报错信息为 `trial period amount should be less than subscription amount`。零是有效的试用金额（免费试用），因此可接受范围为 `0 ≤ trialPeriodAmount < amount`。

如果试用的目的是调整计费日历而不改变价格，请完全不要配置试用——用 `startTime` 推迟首次扣款，或用 `scheduledAmounts` 为特定早期周期定价。


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