> ## 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/change のエンドツーエンドの仕組み：remainingAmount とは何か、誰が計算するのか、4 つの変更ステータス、旧サブスクリプションはいつどうなるのか、顧客が支払わなかった変更を差し替える方法、そして A0048 / A0049 / A0050 / A0054 の意味を説明します。

`/api/v1/subscription/update` は、顧客がすでに持っているサブスクリプションの**金額**を変更するもので、引き下げのみ可能です。それ以外のすべて（別のサイクル、より高い価格、別のプラン、別の通貨）は、`/api/v1/subscription/change` による**プラン変更**です。このページはプラン変更の契約仕様です。金額のみの変更については
[サブスクリプションの金額と期間ごとのスケジューリング](/docs/ja/support/subscription-amount-scheduling-faq)
をご覧ください。

## プラン変更は実際に何を行うのですか？

既存のサブスクリプションを編集するのでは**ありません**。**新しいサブスクリプション**を作成し、顧客に認可してもらい、旧サブスクリプションを退役させます。

1. 元のサブスクリプションの `originSubscriptionRequest`、新しいプランの完全な記述、および新しい `subscriptionRequest` を指定して `/api/v1/subscription/change` を呼び出します。
2. Waffo は新しいサブスクリプションを作成し、`webUrl` を含む `subscriptionAction` を返します。顧客をそこへ送り、新しいプランを認可してもらいます。
3. 顧客が認可し、新しいプランの初回課金が成功すると、変更が確定します。新しいサブスクリプションが `ACTIVE` になり、元のサブスクリプションは退役します。
4. Waffo は、変更リクエストで送信した `notifyUrl` に `SUBSCRIPTION_CHANGE_NOTIFICATION` をプッシュします。`/api/v1/subscription/change/inquiry` は同じ内容をオンデマンドで返します。

したがって、「顧客の既存プランをそのまま編集できるか」という質問への答えは**いいえ**です。稼働中のサブスクリプションのサイクル、期間数、プランを書き換えるエンドポイントはありません。顧客が当初与えたマンデートは旧条件に対するものであるため、顧客は再認可する必要があります。

**`subscriptionId` は変わります。** 変更が確定した時点から、貴社の記録は新しい `subscriptionId` をキーにし、旧 ID は履歴目的のみで保持してください。

## 顧客に支払いページを提示する必要がありますか？それともサイレントに行えますか？

ページを提示する必要があります。変更はチェックアウトで顧客が認可するもので、それが `subscriptionAction.webUrl` の目的です。既存のマンデートを再利用するサーバー間のプラン変更はありません。

顧客が途中で放棄する場合を想定してください。顧客が認可するまでは何も変わっておらず、元のサブスクリプションは通常どおり課金を続けます。

## 変更ステータスにはどのようなものがありますか？

| `subscriptionChangeStatus` | 意味 |
| - | - |
| `IN_PROGRESS` | 支払いリクエストが開始されました。 |
| `AUTHORIZATION_REQUIRED` | 顧客の認可待ちです。`subscriptionAction` に URL が含まれます。 |
| `SUCCESS` | 変更が完了しました。最終状態です。 |
| `CLOSED` | 変更は完了しませんでした。最終状態です。 |

`CLOSED` は意図的に**成功以外のすべての終わり方をまとめた 1 つのバケット**です。顧客の支払いが失敗した、認可の期限が切れた、貴社がこの変更を新しい変更で差し替えた、のいずれもここに入ります。「タイムアウト」と「拒否」を区別するシグナルではないため、そうであるかのように分岐しないでください。

`CLOSED` を見たときにすべきこと：自動的には何もありません。元のサブスクリプションは引き続き存在し、課金を続けています。顧客がまだ新しいプランを希望する場合は、**新しい**変更リクエストを発行してください。旧リクエストをリトライしたり、その `subscriptionRequest` を再利用したりしないでください。

## `remainingAmount` とは何ですか？誰が計算するのですか？

`remainingAmount` はすべての変更リクエストで**必須**であり、**貴社**が計算する値です。Waffo は日割り計算を行わず、日割りのフィールドもありません。
[金額ページ](/docs/ja/support/subscription-amount-scheduling-faq)
の日割りに関するセクションをご覧ください。

Waffo がこの値をどう扱うか：この数値を変更リクエストの `currency` 建ての**変更に対するクレジット残高**として保持し、新しいサブスクリプションの課金に対して引き落としていきます。引き落とし対象となった課金が回収されずにクローズされた場合や、確保した額より少なく引き落とされた場合、未使用分は失われるのではなく残高に戻されます。

実務上のルール：

* これは貴社の数値です。「顧客は 30 日分を支払い、12 日分を使用した」という計算をしたい場合は、貴社側でその計算を行い、結果を送信します。
* 変更リクエストの `currency` 建てで送信してください。自動的に換算されることはありません。
* これは将来の課金に対するクレジットであり、返金ではありません。顧客に将来のクレジットではなく返金が必要な場合は、代わりに元の課金を返金してください。[返金](/docs/ja/support/refund-faq)をご覧ください。
* `remainingAmount` は `/api/v1/subscription/change/inquiry` でも返されるため、ご自身で追跡するのではなく、残額を読み取ることができます。

## プラン変更で通貨や決済手段も切り替えられますか？

どちらも可能です。変更リクエストは新しいサブスクリプションをゼロから記述するものであるため、これらは単にリクエスト上のフィールドです：

| 切り替えたいもの | 方法 |
| - | - |
| 価格設定通貨 | 変更リクエストの `currency`。必須のため、常に再指定することになります。 |
| 顧客への請求通貨 | 変更リクエストの `userCurrency`。 |
| 決済手段 | 変更リクエストの `paymentInfo.payMethodType` / `payMethodName`。顧客はチェックアウトページで再認可するため、まったく別の決済手段でも問題ありません。 |
| サイクル、期間数、トライアル、期間ごとの金額 | `productInfoList` のエントリ。作成時のすべてのフィールドが利用できます。 |
| クーポンまたはプロモーション | `promotionInfo`。`promotionCode` または `couponId` のいずれか（相互排他）。 |

`remainingAmount` は変更リクエストの `currency` 建てで表現されるため、通貨を切り替える場合は繰越額を**新しい**通貨で表現する必要があります。Waffo が旧通貨の残高を換算することはありません。

旧サブスクリプションから引き継がれるものは何もありません。再指定しなかったものはすべて失われ、期間ごとの金額プランも同様です。価格の段階的変更を維持したい場合は、変更リクエストで `scheduledAmounts` を再指定してください。

## 1 つの変更リクエストに複数のプランを含めることはできますか？

`productInfoList` はリストであり、各エントリが 1 つのプランを記述します。これは顧客が移行する**1 つ**のプランのための形式として扱ってください。結果として生じるサブスクリプションは 1 つのサイクル、1 つの期間数、1 つの金額を持つため、2 つの異なるサイクルを記述したリクエストには整合的な意味がありません。顧客が本当に異なるサイクルで 2 つのものを購入するなら、それは 2 つのサブスクリプションです。

## 旧サブスクリプションは即時に停止しますか？それとも期間終了時ですか？

どちらも存在し、**`startTime` で貴社が選択します**：

| 変更リクエストの `startTime` | 新プランの開始 | 元のサブスクリプション |
| - | - | - |
| 省略 | 認可時に即時 | 変更が確定した時点でキャンセル — `MERCHANT_CANCELLED` |
| 将来の時刻 | その日付に | 稼働を継続し、**現在の期間の終了時にキャンセルが予約**されるため、顧客はすでに支払ったサービスを引き続き利用できます |

2 行目が、二重請求なし・スケジューラーの自作なしで「アップグレードは次のサイクルから有効」を実現する方法です。これは Waffo が行う唯一の期間終了時退役でもあります。`/api/v1/subscription/cancel` は常に即時であり、これについては
[ホスト型管理ページ](/docs/ja/support/subscription-hosted-management-faq)
で説明しています。

変更時の `startTime` には 2 つの制約があります：

* **元のサブスクリプションの次回予定課金より前**であってはなりません。顧客がすでに支払った期間内の開始時刻は拒否されます。
* 作成時の一般的な制限も引き続き適用されます：厳密に将来であること、最大 365 日先まで、新しいサブスクリプションを担う契約の有効期間内であること。

将来開始の変更が保留中の間、元のサブスクリプションの更新は実行されずに保留されるため、顧客が離れようとしている期間に対して課金されることはありません。

## 顧客がアップグレードリンクで支払わず、今は別のプランを希望しています

顧客が実際に希望するプランで、`/api/v1/subscription/change` を再度呼び出してください。

その呼び出しの一部として、**Waffo が保留中の変更を清算します**。保留中の新サブスクリプションの未払い課金はキャンセルされ、その新サブスクリプションは差し替え済みとしてクローズされ、保留中の変更は `CLOSED` に移行し、元のサブスクリプションは解放されて新しい変更をその上に構築できるようになります。サポートにクリアしてもらう必要も、別途キャンセル呼び出しを行う必要もありません。「変更のキャンセル」エンドポイントがないのは、まさに次の変更がそれを行うからです。

重要な注意点：清算は失敗することがあり、その場合、新しい変更は作成され**ません**。代わりに以下のいずれかが返され、保留中の変更は引き続き有効なままです：

| コード | メッセージ | 意味 | 対処 |
| - | - | - | - |
| `A0048` | The previous plan change is still in payment | 保留中の変更に対する顧客の支払いが実際にまだ進行中で、キャンセルできません。 | その支払いの結果を待ち、それに基づいて対処してください。`change` をループで呼び出さないでください。 |
| `A0049` | The previous plan change is being cancelled, please retry later | 清算が正常に完了せず、結果がまだ確定していません。 | 少し待ってから同じ変更リクエストをリトライしてください。こちらは本当にリトライ可能です。 |
| `A0050` | The previous plan change has been paid successfully | 貴社が差し替えている間に、顧客が保留中の変更を支払いました。それが現在の顧客の有効なプランです。 | サブスクリプションを再読み込みし、**新しい**有効プランに基づいて**新しい**変更を発行してください。 |
| `A0054` | Another plan change request for this subscription is being processed | 同じサブスクリプションに対する 2 つの変更呼び出しが競合しました。 | 少し待ってからリトライしてください。 |

`A0048` と `A0049` は混同しやすいです。`A0048` は*資金が動いているので、止まって結果を待つ*という意味で、`A0049` は*まだ分からないので、もう一度問い合わせる*という意味です。`A0048` でリトライしても役に立たず、`A0049` を致命的エラーとして扱うと顧客が行き詰まります。

## 金額とプランを同時に変更できますか？

いいえ。いずれかが進行中の間、両者は相互排他です。Waffo はサブスクリプションごとに `update`、`change`、`cancel` を直列化します。1 つが処理中の間、他は `A0055`（"The subscription is being modified, please retry later"）で拒否されます。

`A0055` はリトライ可能です。一括で価格を変更する場合は、失敗ではなくバックプレッシャーとして扱ってください。ただし、同じサブスクリプションに対して `update` と `change` を同時に発行し、両方が成功することを期待しないでください。

## 新プランでは期間ごとの金額とトライアルはどうなりますか？

何も引き継がれません。新サブスクリプションの `amount`、`trialPeriodAmount`、`numberOfTrialPeriod`、`scheduledAmounts` は**すべて変更リクエストから**取得されます。`scheduledAmounts` を省略すると、新サブスクリプションは毎期間、新しい `amount` で課金されます。

アップグレード時にトライアルを付与する前に考慮すべき点：これは新しいサブスクリプションであるため、トライアル期間の番号付けは最初からやり直しになります。すでにトライアルを利用した顧客も、トライアルを設定すれば再度トライアルを受けることになります。

## どのレコードが正となる情報源ですか？

新しい `subscriptionRequest` と `originSubscriptionRequest` をキーとする `/api/v1/subscription/change/inquiry` です。変更ステータス、認可が保留中の間は `subscriptionAction`、現在の `remainingAmount`、および送信した新プランの完全な記述を返します。

`SUBSCRIPTION_CHANGE_NOTIFICATION` は*いつ*確認すべきかを教え、照会は*何が真実か*を教えます。そこから新しい `subscriptionId` を永続化し、変更が `SUCCESS` と読み取れた時点でのみ、権利付与を新しいサブスクリプションに切り替えてください。

## 次はどこを見ればよいですか？

* [サブスクリプションの作成・検証](/docs/ja/support/subscription-creation-validation-faq)
  — 新プランが満たすべき値の範囲と、`startTime` のルール。
* [サブスクリプションの金額と期間ごとのスケジューリング](/docs/ja/support/subscription-amount-scheduling-faq)
  — 代わりに `update` でできること、そして日割りがない理由。
* [サブスクリプションは実際にいつ課金されますか？](/docs/ja/support/subscription-billing-schedule-faq)
  — 新プランの日付がどのように導出されるか。


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