私が運営しているFlutter大学のサブスクの管理でStripeをメインで使っています。
元々StripeのSubcriptionだけを使っていたのですが、年額などを増やした結果それだと回らなくなったので、SubcriptionScheduleを使うようになりました。（そのときの話は以下記事を参考）
SubcriptionScheduleを使うようになってかれこれ１年くらい経ちますが、またハマりどころを発見したので共有します。
問題は、SubcriptionScheduleのサイクルが走っている時に、SubcriptionをUpdateしようとするとエラーになるということです。（ユーザーの挙動としては退会やプラン変更など）
SubcriptionScheduleのサイクルがあるときは、SubcriptionScheduleをupdateする必要があり、Subscription自身をupdateすることはできません。
対処方法の結論
私のケースの対処方法の結論としては、ユーザーのプラン変更時や退会時にSubcriptionScheduleがあるときはSubcriptionScheduleを更新し、ないときはSubcriptionを更新しよう となります。
コードに示した場合、ざっくり以下のようになります。（fetchActiveSubscriptionSchedulesはstripeAPIをラップした自前の関数です）
final schedules = await fetchActiveSubscriptionSchedules(
customerId: customerId,
);
final scheduleId = schedules.firstOrNull?.id;
if (scheduleId != null) {
// サブスクリプションスケジュールを更新
} else {
// サブスクリプションを更新
}
以下は、もう少し詳しい説明です。
SubscriptionとSubscriptionScheduleって何？
まず、SubscriptionとSubscriptionScheduleの関係性について改めて解説します。
以下の課題学習プランと書いているものがSubscriptionです。それに対してUpdated Scheduledというマークがついています。これがSubscriptionScheduleに関係しています。
つまり、あるサブスクに対して、いつからどのように変更を加えるかという情報がSubscriptionScheduleです。
このテストユーザーの場合は、以下のように2025年1月11日に課題学習プランからコミュニティプランに変更という情報が付与されています。この情報がSubscriptionScheduleです。（以下は厳密にはSubscriptionScheduleが持つphasesという情報）
SubscriptionScheduleはいつ消える？
注意なのは、このSubscriptionScheduleは2025年1月11日をすぎてコミュニティプランへの変更が完了したとしても消えないことです。2025年2月11日になってこのスケジュール変更が完遂されるまでは維持されます。
SubscriptionScheduleのObjectにはend_behaviorというパラメータがあって、releaseとcancelがあるのですが、releaseにしてた場合、2025年2月11日になったらそのままコミュニティプランを継続してSubscriptionScheduleは消えます。また、cancelにしてた場合はこの親のSubcriptionが2025年2月11日にキャンセルされます。つまり、Flutter大学の仕様でいうと退会です。
end_behaviorのrelaseのリリースは、2025年1月11日にコミュニティプランに変わった瞬間なのかなと最初私は勘違いしていましたが、これはコミュニティプランがしっかり１ヶ月経過するまでなようです。
ただ、下図のように、管理画面上でのぱっと見はスケジュールの概念は消えたように見えます。ちょっと紛らわしいですね。
まとめ
SubscriptionScheduleを作った場合、そのサブスクに何か変更を加えたい時に要注意です。処理を分岐させる必要があります。
この記事が誰かのサブスクサービスにお役に立てると幸いです！
Discussion