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

# 增加席位并补差价

> 了解 Subscription 当前周期补差的关键字段。

本页介绍活跃 Subscription 在当前周期增购后立即补差的使用案例，以及需要关注的关键字段。

调用 `POST /api/v1/subscription/update` 可以同时更新后续周期金额，并为当前周期创建即时补差订单。

| 请求关键字段                                   | 作用                       |
| ---------------------------------------- | ------------------------ |
| `subscriptionRequest` 或 `subscriptionId` | 标识需要更新的 Subscription     |
| `amount` 或 `productInfo`                 | 更新下一周期开始生效的计费信息          |
| `topupInfo`                              | 创建当前周期的即时补差订单；省略时只更新后续周期 |
| `topupInfo.topupRequest`                 | 标识本次补差请求；每次补差使用唯一值以保持幂等  |
| `topupInfo.topupAmount`                  | 设置当前周期需要立即收取的补差金额        |

| 响应关键字段                       | 作用                 |
| ---------------------------- | ------------------ |
| `previousAmount`             | 更新前的周期金额           |
| `newAmount`                  | 下一周期开始使用的新金额       |
| `nextEffectivePeriod`        | 新计费信息开始生效的周期       |
| `topupInfo.acquiringOrderId` | 即时补差订单 ID，用于查询支付结果 |
| `topupInfo.topupStatus`      | 即时补差订单的当前状态        |
| `topupInfo.topupAction`      | 需要用户授权时返回的操作信息     |

### 行为规则

* `topupAmount` 只收取当前周期补差。
* 更新后的 `amount` 或 `productInfo` 从下一周期开始生效。
* 即时补差不会改变原 Subscription 的账期日期和周期序号。
* 当 `topupStatus` 为 `AUTHORIZATION_REQUIRED` 时，将 `topupAction` 解析为 JSON 字符串，并把用户跳转到其中的 `webUrl`。
* 通过 Payment order notification 获取支付终态。通知丢失或超时时，使用 `acquiringOrderId` 调用 `POST /api/v1/order/inquiry` 查询。
* 不要把浏览器跳转结果作为支付成功依据。