/api/v1/subscription/update は、顧客がすでに持っているサブスクリプションの金額を変更するもので、引き下げのみ可能です。それ以外のすべて（別のサイクル、より高い価格、別のプラン、別の通貨）は、/api/v1/subscription/change によるプラン変更です。このページはプラン変更の契約仕様です。金額のみの変更については
サブスクリプションの金額と期間ごとのスケジューリング
をご覧ください。
プラン変更は実際に何を行うのですか？
既存のサブスクリプションを編集するのではありません。新しいサブスクリプションを作成し、顧客に認可してもらい、旧サブスクリプションを退役させます。- 元のサブスクリプションの
originSubscriptionRequest、新しいプランの完全な記述、および新しいsubscriptionRequestを指定して/api/v1/subscription/changeを呼び出します。 - Waffo は新しいサブスクリプションを作成し、
webUrlを含むsubscriptionActionを返します。顧客をそこへ送り、新しいプランを認可してもらいます。 - 顧客が認可し、新しいプランの初回課金が成功すると、変更が確定します。新しいサブスクリプションが
ACTIVEになり、元のサブスクリプションは退役します。 - Waffo は、変更リクエストで送信した
notifyUrlにSUBSCRIPTION_CHANGE_NOTIFICATIONをプッシュします。/api/v1/subscription/change/inquiryは同じ内容をオンデマンドで返します。
subscriptionId は変わります。 変更が確定した時点から、貴社の記録は新しい subscriptionId をキーにし、旧 ID は履歴目的のみで保持してください。
顧客に支払いページを提示する必要がありますか？それともサイレントに行えますか？
ページを提示する必要があります。変更はチェックアウトで顧客が認可するもので、それがsubscriptionAction.webUrl の目的です。既存のマンデートを再利用するサーバー間のプラン変更はありません。
顧客が途中で放棄する場合を想定してください。顧客が認可するまでは何も変わっておらず、元のサブスクリプションは通常どおり課金を続けます。
変更ステータスにはどのようなものがありますか？
CLOSED は意図的に成功以外のすべての終わり方をまとめた 1 つのバケットです。顧客の支払いが失敗した、認可の期限が切れた、貴社がこの変更を新しい変更で差し替えた、のいずれもここに入ります。「タイムアウト」と「拒否」を区別するシグナルではないため、そうであるかのように分岐しないでください。
CLOSED を見たときにすべきこと：自動的には何もありません。元のサブスクリプションは引き続き存在し、課金を続けています。顧客がまだ新しいプランを希望する場合は、新しい変更リクエストを発行してください。旧リクエストをリトライしたり、その subscriptionRequest を再利用したりしないでください。
remainingAmount とは何ですか？誰が計算するのですか？
remainingAmount はすべての変更リクエストで必須であり、貴社が計算する値です。Waffo は日割り計算を行わず、日割りのフィールドもありません。
金額ページ
の日割りに関するセクションをご覧ください。
Waffo がこの値をどう扱うか：この数値を変更リクエストの currency 建ての変更に対するクレジット残高として保持し、新しいサブスクリプションの課金に対して引き落としていきます。引き落とし対象となった課金が回収されずにクローズされた場合や、確保した額より少なく引き落とされた場合、未使用分は失われるのではなく残高に戻されます。
実務上のルール：
- これは貴社の数値です。「顧客は 30 日分を支払い、12 日分を使用した」という計算をしたい場合は、貴社側でその計算を行い、結果を送信します。
- 変更リクエストの
currency建てで送信してください。自動的に換算されることはありません。 - これは将来の課金に対するクレジットであり、返金ではありません。顧客に将来のクレジットではなく返金が必要な場合は、代わりに元の課金を返金してください。返金をご覧ください。
remainingAmountは/api/v1/subscription/change/inquiryでも返されるため、ご自身で追跡するのではなく、残額を読み取ることができます。
プラン変更で通貨や決済手段も切り替えられますか？
どちらも可能です。変更リクエストは新しいサブスクリプションをゼロから記述するものであるため、これらは単にリクエスト上のフィールドです：remainingAmount は変更リクエストの currency 建てで表現されるため、通貨を切り替える場合は繰越額を新しい通貨で表現する必要があります。Waffo が旧通貨の残高を換算することはありません。
旧サブスクリプションから引き継がれるものは何もありません。再指定しなかったものはすべて失われ、期間ごとの金額プランも同様です。価格の段階的変更を維持したい場合は、変更リクエストで scheduledAmounts を再指定してください。
1 つの変更リクエストに複数のプランを含めることはできますか？
productInfoList はリストであり、各エントリが 1 つのプランを記述します。これは顧客が移行する1 つのプランのための形式として扱ってください。結果として生じるサブスクリプションは 1 つのサイクル、1 つの期間数、1 つの金額を持つため、2 つの異なるサイクルを記述したリクエストには整合的な意味がありません。顧客が本当に異なるサイクルで 2 つのものを購入するなら、それは 2 つのサブスクリプションです。
旧サブスクリプションは即時に停止しますか？それとも期間終了時ですか？
どちらも存在し、startTime で貴社が選択します：
2 行目が、二重請求なし・スケジューラーの自作なしで「アップグレードは次のサイクルから有効」を実現する方法です。これは Waffo が行う唯一の期間終了時退役でもあります。
/api/v1/subscription/cancel は常に即時であり、これについては
ホスト型管理ページ
で説明しています。
変更時の startTime には 2 つの制約があります：
- 元のサブスクリプションの次回予定課金より前であってはなりません。顧客がすでに支払った期間内の開始時刻は拒否されます。
- 作成時の一般的な制限も引き続き適用されます：厳密に将来であること、最大 365 日先まで、新しいサブスクリプションを担う契約の有効期間内であること。
顧客がアップグレードリンクで支払わず、今は別のプランを希望しています
顧客が実際に希望するプランで、/api/v1/subscription/change を再度呼び出してください。
その呼び出しの一部として、Waffo が保留中の変更を清算します。保留中の新サブスクリプションの未払い課金はキャンセルされ、その新サブスクリプションは差し替え済みとしてクローズされ、保留中の変更は CLOSED に移行し、元のサブスクリプションは解放されて新しい変更をその上に構築できるようになります。サポートにクリアしてもらう必要も、別途キャンセル呼び出しを行う必要もありません。「変更のキャンセル」エンドポイントがないのは、まさに次の変更がそれを行うからです。
重要な注意点：清算は失敗することがあり、その場合、新しい変更は作成されません。代わりに以下のいずれかが返され、保留中の変更は引き続き有効なままです：
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 と読み取れた時点でのみ、権利付与を新しいサブスクリプションに切り替えてください。
次はどこを見ればよいですか？
- サブスクリプションの作成・検証
— 新プランが満たすべき値の範囲と、
startTimeのルール。 - サブスクリプションの金額と期間ごとのスケジューリング
— 代わりに
updateでできること、そして日割りがない理由。 - サブスクリプションは実際にいつ課金されますか？ — 新プランの日付がどのように導出されるか。