> ## 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` を呼び出すと、将来の請求額を更新し、当期分の即時差額オーダーを1回のリクエストで作成できます。

| 主要リクエストフィールド                               | 用途                                     |
| ------------------------------------------ | -------------------------------------- |
| `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` を呼び出します。
* ブラウザーのリダイレクトを決済成功の根拠にしないでください。