サブスクリプションのリクエストにおける scheduledAmounts とは何ですか？
scheduledAmounts は productInfo 内の任意のリストで、毎期間同じ amount を請求する代わりに、
特定の請求期間に異なる金額を請求できるようにします。各エントリはちょうど 2 つのフィールドを持ちます。
amount にフォールバックし、列挙する期間は連続している必要はありません。
第 1 期と第 5 期だけを列挙するのも有効です。
scheduledAmounts はサブスクリプション作成時に設定でき、後から /api/v1/subscription/update で変更できます。
period は最初の期間から数えますか、それともトライアル後の最初の期間から数えますか？
サブスクリプションの最初の期間からです。 period はすべての請求期間にわたる絶対的な 1 始まりのインデックスであり、
トライアル期間もその数に含まれます。
これはトライアルが存在するときに重要になります。2 期間のトライアルを設定した場合、period: 1 と period: 2 は
2 つのトライアル期間を指し、通常価格での最初の期間は period: 3 になります。
どこにもオフセットは適用されません。Waffo はこれから作成する請求の期間番号を調べ、その番号ちょうどで
scheduledAmounts を参照します。稼働中のサブスクリプションが現在どこにいるかは、/api/v1/subscription/inquiry の
productInfo.currentPeriod を読んでください。保存されているプランは同じレスポンスの
productInfo.scheduledAmounts として返るため、更新を送る前にどの期間番号がまだ将来なのかを常に確認できます。
Waffo は各期間の金額をどのように決めますか？
3 つの入力がこの順序で参照され、最後に一致したルールが適用されます。
したがって、
scheduledAmounts のエントリはその期間についてトライアル金額を上書きします。トライアルを
trialPeriodAmount で請求したい場合は、トライアル期間の番号を scheduledAmounts に列挙しないでください。
請求が想定と一致しないときに最初に確認すべきはこれです。その請求の期間番号を割り出し、3 つのルールを順に辿ってください。
scheduledAmounts の正確な制限は何ですか？
逆に想定されがちな 2 点を明示しておきます。
- 金額は最小単位ではなく、通貨の通常の単位での小数文字列です。
"990"ではなく"9.90"です。余分な小数桁は 丸められるのではなく拒否されます。 amount: "0"はフィールドのバリデーションを通過するため、無料の期間を表現できます。ただしその値は契約上の 最小金額を満たす必要があるため、0 が受け付けられるかどうかは契約次第です。
次の期間のサブスクリプション金額を直接引き上げられますか？
いいえ。/api/v1/subscription/update ではできません。 既定では、このエンドポイントはあらゆる引き上げを拒否します。
これは 3 つの金額フィールドすべてで強制されます。
期間ごとの基準値は、その同じ期間について現在保存されているスケジュール金額、またはその期間が保存済みプランに
ない場合はサブスクリプションの
amount です。これにより明らかな抜け道が塞がれます。ある期間をいったん引き下げてから
2 回目の呼び出しで元に戻すことはできません。2 回目の呼び出しは、たった今書き込んだ値と比較されるからです。
違反はパラメーターエラーとして返り、メッセージには拒否された内容が示されます
（amount is not allowed to increase、
trialPeriodAmount is not allowed to increase、
scheduledAmounts.amount is not allowed to increase for period N）。
より多く請求するには、/api/v1/subscription/change を使ってユーザーを新しいプランに移すか、引き上げが
シート追加である場合は topupInfo ブロックを付けて更新を送ってください。この経路は現在の期間の差額を直ちに回収し、
次の期間から amount を引き上げることが許可されています（下の日割りの表を参照）。update による単純な引き上げは
一般のアカウントには開放されていません。連携上どうしても必要だと考える場合は、回避策を設計するのではなく
連携サポートに相談してください。
日割り計算（prorate）はどう設定しますか？
日割りのフィールドは存在せず、Waffo は日割り計算を行いません。prorate / proration_behavior のような
パラメーターを探している場合、それは /subscription/update にも /subscription/change にも存在しません。
貴社側で何を実装すべきかを判断できるよう、各ケースで実際に何が起こるかを示します。
要するに、金額の変更は期間の境界で起こるイベントであり、変更が期間の途中に発生したことによって動かすべき資金は、
貴社が計算し、貴社が回収するものです。
/subscription/update は正確に何を変更し、いつ有効になりますか？
変更するのは金額のみで、次の請求期間以降に適用されます。
変更できるもの： amount、productInfo.trialPeriodAmount、productInfo.scheduledAmounts。個別にも組み合わせても
可能です。3 つのうち少なくとも 1 つが存在しなければリクエストは拒否されます。
変更しないもの： プラン、periodType、periodInterval、残りの期間数、請求日、決済手段。日割りを発生させず、
新しいサブスクリプションも作成しません。
タイミング： 新しい値は次の期間から適用されます。すでに生成済み、または進行中である現在の期間の請求には
影響しません。レスポンスは変更が適用される期間番号を示します。
金額の更新はどのような場合に直ちに拒否されますか？
最後の行は、更新がサブスクリプションごとに直列化されることを意味します。多数のサブスクリプションを再価格設定する
場合、「変更処理中のため後で再試行してください」というレスポンスは失敗ではなくリトライ可能なものとして扱ってください。
更新で scheduledAmounts を送ると、既存のプランとマージされますか？
いいえ。送信したリストが保存済みプラン全体を置き換えます。 パッチではありません。旧プランに存在してリクエストに
ない期間はスケジュール金額を失い、amount にフォールバックします。
設計上考慮すべき 2 つの帰結：
- 変更する期間だけでなく、価格を設定したい将来の期間の完全なセットを常に送信してください。
- 更新は現在の期間より後の期間しか指定できないため、すでに請求済みの期間のエントリはプランを置き換える際に 保存から除かれます。これは想定どおりで、すでに発生した請求が変わることはありません。
/subscription/update でスケジュール金額のプランをクリアする方法はありません。単一の一律金額に戻すには、
残りの将来の期間すべてを希望の金額で列挙するか、/subscription/change でユーザーを新しいプランに移してください。
アップグレードやダウングレードのとき、scheduledAmounts はどうなりますか？
何も引き継がれません。/subscription/change は新しいサブスクリプションを作成し、その新しいサブスクリプションの
amount と scheduledAmounts はすべて変更リクエストから取られます。そこで scheduledAmounts を省略すると、
新しいサブスクリプションには期間ごとのプランがまったくなく、すべての期間が新しい amount で請求されます。
したがって、段階的な価格の推移をアップグレード後も維持したい場合は、変更リクエストで改めて記述する必要があります。
エンドユーザーに金額の変更は伝えられますか？
はい。金額の更新が成功すると、Waffo は加入者にメールを送信します。メールには変更前の金額、新しい金額、変更前と 変更後の期間ごとのプラン、そして変更が有効になる期間番号が記載されます。 運用上の注意が 2 点：- メールは、貴社のアカウントとプロダクトで金額変更の通知が有効になっている場合にのみ送信されます。オフになっていれば ユーザーには何も送信されません。
- 送信はベストエフォートかつ非同期です。メールの失敗によって金額の変更がロールバックされることはありません。 変更内容の記録は API のレスポンスです。
金額の更新が成功したとき、Waffo は Webhook を送りますか？
はい。/subscription/update が成功すると、Waffo はサブスクリプションに保存された notifyUrl に
SUBSCRIPTION_UPDATE_NOTIFICATION をプッシュします。単純な金額変更では更新が確定した時点で送信され、
シート追加（下記参照）ではトップアップの請求が成功して新しい金額が適用された時点で送信されます。ペイロードは
照会 API が返すサブスクリプションそのものなので、すでに新しい金額が反映されています。
貴社の記録を揃えるために：
/subscription/updateのレスポンスを主たる記録として扱い、newAmount、newScheduledAmounts、nextEffectivePeriodを読み取って保存してください。Webhook は同じ変更を非同期に確認するものであり、変更が 即時のリクエスト経路の外で確定した場合（トップアップのケース）に使うべきシグナルです。- 各期間の実際に請求された金額については、期間ごとの通知とサブスクリプション決済注文の通知を引き続き受信して ください。それらが実際に徴収された金額を反映しており、照合すべき数値です。
そもそもどのサブスクリプションが期間ごとの金額を使えますか？
期間ごとの金額と/subscription/update は、Waffo が請求スケジュールを駆動するサブスクリプションで利用できます。
一部の決済手段では決済手段自身がスケジュールを駆動します。そのようなサブスクリプションは作成時に scheduledAmounts を
拒否し、金額更新の対象にもなりません。作成呼び出しでスケジュール金額がそのサブスクリプションではサポートされていないと
返ってきた場合の理由はこれです。修正すべきはリクエストの形ではなく、別の決済手段です。