API と高度な使用法

ダッシュボードと API でテストクロックを使用するための高度な戦略をご紹介します。

高度なシミュレーションを実行するために、サブスクリプションとは別にテストクロックを作成できます。このシナリオでは、まずテストクロックを作成してから、そこにさまざまなテストケースを追加します。

完全統合型のソリューションをご希望でない場合、サブスクリプションのシミュレーションの実行についてStripe のガイドをご覧ください。

テストクロックを設定して、サブスクリプションの時間経過をシミュレーションする方法。

テストクロックのライフサイクル

以下の手順でテストクロックの使用を開始します。

テストクロックを作成する
テスト用のシミュレーションを設定する
クロックの時間を進める
変更をモニターして処理する
シミュレーションを更新する
クロックを削除する

テストケースごとに必要に応じてクロックの時間を進めたり、変更をモニターしたり、シミュレーションを更新したりできます。

クロックを作成して時間を設定する

シミュレーションを開始するには、クロックを作成し、その凍結時刻を設定します。これは、クロックに関連付けられたすべてのサブスクリプションの時間的な開始点です。この時刻は過去または未来に設定して、さまざまなシミュレーションをテストできますが、設定後は進行のみが可能になります。

ダッシュボードでテストクロックを作成するには、下記のステップを実行します。ダッシュボードをテスト環境に設定して、テストクロックを使用します。

Billing タブのサブスクリプションセクションに移動します。
バナーのテストクロックのリンクをクリックします。
新しいシミュレーションをクリックします。
新しいシミュレーションの作成モーダルで、シミュレーションの名前を入力します。Annual renewal や Free trial など、この名前を使用して、テストするシミュレーションを説明することができます。
クロックの凍結時刻を設定します。これは、シミュレーションの開始点です。この時刻は過去または未来に設定できますが、設定後は進行のみが可能になります。

シミュレーションを設定する

次に、シミュレーションのためのテストケースを設定します。まず顧客を作成してから、その顧客のためのサブスクリプションを作成する必要があります。

ダッシュボードでシミュレーション用の顧客を作成するには、以下のようにします。

テストクロックのページに移動して、テストクロックを探します。
追加 > 顧客を追加をクリックします。

テストクロックのシミュレーション中は、既存の顧客を選択できません。シミュレーションごとに新しい顧客を 3 人まで追加できます。

オプションで、顧客の名前、メールアドレス、請求情報などの他の使用できるプロパティを入力することができますが、いずれも必須ではありません。無料トライアルのテストなどの一部のシミュレーションでは、請求情報を事前に収集する必要はありません。

次に、顧客に 3 件までのサブスクリプションまたはサブスクリプションのスケジュールを作成できます。ダッシュボードを使用して顧客のサブスクリプションを作成するには、以下のようにします。

テストクロックのページに移動して、テストクロックを探します。
追加 > サブスクリプションを追加をクリックして、ドロップダウンメニューから顧客を選択または検索します。また、顧客ページでアクション > サブスクリプションを作成をクリックして、顧客をサブスクリプションに追加することもできます。
料金体系セクションで継続支払いの商品と価格を選択します。
サブスクリプションのスケジュールでは、サブスクリプションの開始日と終了日、および請求サイクルの開始日を定義します。
支払いの回収方法を選択します。
- 請求サイクルの開始時に顧客に請求する場合は、登録されている支払い方法に自動的に請求するを選択します。
- 顧客に後から請求書を送付するには、手動支払い用の請求書を顧客にメールで送付するを選択します。
テストのサブスクリプションを開始をクリックして、サブスクリプションと請求サイクルを開始します。

最初のステップで作成した Clock オブジェクトに Customer と Subscription の両方のオブジェクトが関連付けられます。ダッシュボードでは、アイコンにより、オブジェクトがクロックに関連付けられたことが示されます。

シミュレーションの時間を進める

テストクロックを作成してテストケースを設定した後で、クロックのシミュレーションの時間を進めます。初めて時間を進める場合は、クロックの作成時に設定した元の凍結時刻から時間を進めることになります。時間を進めることで、サブスクリプションの終了時、更新時、またはその他の変化が発生したとき (無料トライアルから有料のサブスクリプションへのアップグレードなど) に、システムがどのように機能するかを確認できます。

テストクロックは任意の期間で進めることができますが、一度に進めることができるのは元の凍結時刻から最大 2 期間までです。この期間の長さは、テストクロックに関連付けられた最短のサブスクリプション期間に基づき、継続価格によって決まります。たとえば月次のサブスクリプションがある場合、一度に進めることができるのは、2 カ月までです。テストクロックにサブスクリプションまたはサブスクリプションのスケジュールがない場合は、元の凍結時刻から最大 2 年間進めることができます。

ダッシュボードで時間を進めるには、以下のようにします。

テストクロックのページに移動して、テストクロックを探します。
時間を進めるをクリックします。
カレンダーモーダルを使用して、クロックを先に進める日付を選択します。
進めるをクリックします。

クロックの時間の進行が完了すると、バナーが更新され、クロックの現在の時間が表示されます。

変更を監視して処理する

API リクエストまたはダッシュボード操作が成功すると、クロックは数秒後に指定された時間に進みます。いつクロックの状態が変化したかを知るには、Ｗebhook を使用してイベント通知をリッスンするか、クロックをポーリングします。ダッシュボードにも変更が反映されます。たとえば、請求書ページにアクセスして、サブスクリプションの請求書が作成されたか、または支払われたかを確認できます。

Webhook を使用している場合には、以下のイベント通知をリッスンします。本番環境に移行する前に、システムが、以下に記載されたものに加え、その他の請求固有のイベント通知も正しく処理することを確認してください。

イベント	説明
`test_helpers.test_clock.advancing`	クロックは進み始めましたが、指定された時間に達していません。
`test_helpers.test_clock.ready`	クロックは、指定された時間への進行を終了しました。

クロックの状態をポーリングするには、ID を使用して状態を取得し、status を調べます。

シミュレーションを更新する

続けて変更を加え、以下のようなシミュレーションに合わせてクロックを進めることができます。

顧客の残高を追加する。
サイクルの途中でアップグレードする。
1 回限りの請求書アイテムを追加する。

それぞれの更新の後、再び変更を監視します。テストケースに対応するために、必要に応じて何回も繰り返します。

クロックを削除する

テストクロックは、作成から 30 日経過すると自動的に削除されますが、テストの終了後に削除してテスト環境を整然と保つことができます。

ダッシュボードでクロックとすべての関連するテストオブジェクトを削除するには、次のようにします。

テストクロックのページに移動して、テストクロックを探します。
シミュレーションを終了をクリックします。
確認モーダルで、終了をクリックします。

クロックを削除すると、クロックに関連付けられたテスト用の顧客も削除され、そのサブスクリプションがキャンセルされます。テストクロックはテスト環境のみで使用できるため、クロックを削除しても本番環境のオブジェクトは何も削除されません。

Use cases

サブスクリプションの更新をテストする

まず、以下の手順でテストクロックの使用を開始します。

テストクロックを作成する
テスト用のシミュレーションを設定する
クロックの時間を進める
変更をモニターして処理する
シミュレーションを更新する

次に、テストクロックを使用して特定のサブスクリプションの更新をテストできます。たとえば、月額 50 USD のサブスクリプションが正しく更新されるかどうかをテストするとします。テストクロックを使用してこの状況をシミュレーションするには、以下のようにします。

新しいテストクロックを作成して frozen_time を 1 月 1 日に設定します。
顧客を追加して、その顧客の支払い方法を追加します。

ダッシュボードで顧客の支払い方法を追加するには、以下のようにします。

顧客のアカウントページで、支払い方法セクションの追加 > カードを追加をクリックします。
決済情報を入力します。ここでは、テストカードを使用します。
モーダルのカードを追加をクリックします。

顧客の支払い方法を追加した後、新しい顧客に対して月額 50 USD に設定されたサブスクリプションを作成します。そうすると、50 USD の請求書が自動的に支払われ、サブスクリプションは active になります。
日付を 2 月 1 日に進めて、50 USD の請求書が作成されたことを確認します。デフォルトでは、請求書は 1 時間にわたって draft 状態で表示されます。
時間を 1 時間進めて、請求書が確定され、自動的に支払われることを確認します。

比例配分が適用されるサイクル途中のアップグレードをテストする

まず、以下の手順でテストクロックの使用を開始します。

テストクロックを作成する
テスト用のシミュレーションを設定する
クロックの時間を進める
変更をモニターして処理する
シミュレーションを更新する

次に、請求サイクルの途中でプランをアップグレードする顧客の比例配分 (日割り / 秒割り計算) をテストできます。たとえば、2 つの商品があるとします。1 つの商品は月額 50 USD (‘basic plan’) で、もう 1 つの商品は月額 100 USD (‘premium plan’) です。この場合、請求サイクルの途中で ‘basic plan’ を ‘premium plan’ にアップグレードする顧客の比例配分をテストできます。テストクロックを使用してこの状況をシミュレーションするには、以下のようにします。

新しいテストクロックを作成して frozen_time を 1 月 1 日に設定します。
顧客を作成して支払い方法を追加します。ここでは、テストカードを使用します。
‘basic plan’ の月額 50 USD のサブスクリプションを作成します。これを完了すると、月額 50 USD の請求書が作成され、確定されて自動的に支払われたことが分かります。
日付を 2 週間進めます。ここでは日付を 1 月 16 日に設定します。
サブスクリプションを月額 100 USD の ‘premium plan’ にアップグレードします。

ダッシュボードを使用してサブスクリプションをアップグレードするには、以下のようにします。

顧客のアカウントページまたはサブスクリプションの詳細ページで、サブスクリプションに関連するオーバーフローメニュー () をクリックして、サブスクリプションを更新を選択します。
必要な変更を行います。
右上隅にあるサブスクリプションを更新をクリックして、変更を適用します。

サブスクリプションをアップグレードした後、customer.subscription.updated Webhook イベントが作成されます。
比例配分の場合は保留中の請求書アイテムも作成されます。‘basic plan’ の未使用時間に対するマイナスの比例配分 -25 USD と、残り半月における ‘premium plan’ の使用に対するプラスの比例配分 50 USD が示されます。この時点では、請求書は生成されません。
日付を 2 週間進めます。ここでは日付を 2 月 1 日に設定します。サブスクリプションが循環したことが分かります。請求書が draft 状態で生成され、マイナスの比例配分、プラスの比例配分、2 月の支払い総額を含む保留中の請求書アイテムが取り込まれ、125 USD になっています。デフォルトでは、請求書は約 1 時間にわたって draft 状態で表示されます。
請求書を確定するには、時間を 1 時間進めます。

トライアルをテストする

まず、以下の手順でテストクロックの使用を開始します。

次に、テストクロックを使用してトライアルのテストを開始できます。たとえば、顧客に支払いを開始する前に 7 日間のトライアルで商品を無料で試してもらい、決済情報は事前に収集するとします。テストクロックを使用してこの状況をシミュレーションするには、以下のようにします。

新しいテストクロックを作成して frozen_time を 1 月 1 日に設定します。
顧客を追加して支払い方法を含めます。ここでは、のテストカードを使用します。
サブスクリプションを作成して、7 日間無料のトライアル期間を追加します。

ダッシュボードから既存のサブスクリプションにトライアル期間を追加するには、以下を行います。

変更するサブスクリプションを探します。

アクションをクリックします。
サブスクリプションを更新をクリックします。
無料トライアルを追加をクリックして、無料トライアルの日数フィールドに 7 を入力します。
サブスクリプションを更新をクリックします。

7 日間無料のトライアル期間を設けてサブスクリプションを作成すると、サブスクリプションが trialing 状態で作成されます。無料トライアルであるため、$0.00 の請求書が生成されます。
日付を 1 月 5 日に進めて、customer.subscription.trial_will_end のイベント通知を確認します。Stripe はトライアル終了の 3 日前に通知を送信します。この Webhook イベントを使用して、トライアルがまもなく終了することを顧客に通知できます。
日付を 1 月 8 日に進めて、サブスクリプションが paid になり、50 USD の請求書が作成されたことを確認します。
サイクルを 1 つ (月次サブスクリプションの場合は 2 月 8 日まで) 進めて、サブスクリプションが更新されることを確認します。

制限事項

テストクロックを効率的に進めるために、Stripe は、各シミュレーションの複雑度に関する制限を以下のように設定しています。

3 名の顧客
顧客ごとに 3 件のサブスクリプション (スケジュール済みサブスクリプションを含む)
顧客に関連付けられていない 10 件の見積もり

すべての結果のリストで省略されたテストクロックオブジェクト

Stripe のリスト API (請求書の一覧など) では、すべてのリクエストを一覧表示するテストクロックで生成された結果が省略されます。これらのケースでテストクロックによって生成された結果を確認するには、test_clock、customer、または subscription など、特定の親内の結果をリクエストする必要があります。

たとえば、GET /v1/invoices はテストクロックで生成された請求書を返しませんが、GET /v1/invoices/{customer_id} は、テストクロックで生成されたものも含め、その顧客のすべての請求書を返します。

同様に、この例でテストクロック ID を指定して、そのテストクロックに関連するすべての請求書を取得することも、サブスクリプション ID を指定して、テストクロックによって生成された請求書を含む、そのサブスクリプションに対して請求されたすべての請求書を返すこともできます。

レート制限エラー

テストクロックが設定されたサブスクリプションに対して複数回の更新を行うと、Stripe からレート制限エラーが返されることがあります。サブスクリプションはテストクロックの時刻まで凍結されているため、その時刻までのすべての API リクエストがカウントされ、レート制限がトリガーされる可能性があります。

これを回避するには、サブスクリプションで追加の API リクエストを行う前に、シミュレーションされたクロックの時刻を数分進めます。

決済処理の注意事項

現在、テストクロックの進行は銀行口座引き落としによる支払いの回収 (支払い方法のタイプ us_bank_account など) に対応していません。Stripe は、テストクロックが時間を進めた後で支払いを回収します。支払いの失敗をテストするには、次の手順を実行します。

Cancel subscription after all payment retries fail (すべての支払いの再試行が失敗した後にサブスクリプションをキャンセルする) 設定を選択します。
支払いが失敗した顧客に us_bank_account の支払い方法のタイプを追加します。
その顧客でサブスクリプションを作成します。
テストクロックを進めて、サブスクリプションで支払いを繰り返して回収します。

テストクロックが時間を進めた後、サブスクリプションのステータスは active のままになります。これは、テストクロックの進行中に支払いの回収が試行されなかったことを示し、サブスクリプションは payment_failed による canceled ステータスにはまだなっていません。

invoice.payment_failed イベントをリッスンして、遅延が生じたサブスクリプションのステータスと請求書の支払いをモニターします。customer.subscription.deleted イベントは、サブスクリプションのステータスが canceled に設定されたことを示します。