API と高度な使用法

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

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

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

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

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

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

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

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

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

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

ダッシュボードでテストクロックを作成するには、以下の手順に従います。サンドボックスを作成してテストクロックを使用します。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

変更を監視して処理する

API リクエストまたはダッシュボード操作が完了すると、Clock は指定した時刻まで進むまでに数秒かかります。Clock のステータスが変更されたことを知るには、webhook でイベント通知を受信するか、Clock をポーリングして確認します。ダッシュボードにも変更が反映されます。たとえば、invoices page にアクセスして、サブスクリプションの請求書が作成、または支払われたかを確認できます。

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

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

Clock のステータスをポーリングするには、Clock を ID で取得して、ステータス を調べます。

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

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

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

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

クロックを削除する

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

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

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

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

ユースケース

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

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

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

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

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

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

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

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

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

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

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

次に、請求期間の途中でプランをアップグレードする顧客の比例配分をテストできます。2 つの製品があるとします。1 つの製品は 50 USD/月 (「基本プラン」) で、もう 1 つは 100 USD/月 (「プレミアムプラン」) です。この場合、請求期間の途中で「基本プラン」から「プレミアムプラン」にアップグレードする顧客の比例配分をテストしたい場合があります。テストクロックを使用してこの状況をシミュレートするには以下のようにします。

新しいテストクロックを作成して 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 リクエストを行う前に、シミュレーションされたクロックの時刻を数分進めます。

Subscriptions API は、最大リクエスト数を次のように制限します。

新規請求書10件/分 (1サブスクリプション)
新規請求書20件/日 (1サブスクリプション)
数量更新200件/時間 (1サブスクリプション)

決済処理の注意事項

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

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

テスト用 Clock を進めた後も、サブスクリプションのステータスは active のままです。これは、テスト Clock の時間進行中に支払いの回収が行われなかったことを示しています。また、サブスクリプションは payment_failed になったことで canceled のステータスに移行したわけではありません。

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