コンテンツにスキップ
アカウントを作成
または
サインイン
Stripe ドキュメントのロゴ
/
アカウントを作成
サインイン

API と高度な使用法

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

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

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

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

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

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

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

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

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

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

API では、frozen_time フィールドに Unix Epoch のタイムスタンプとして時刻を指定します。この例では、Annual renewal クロックの凍結時刻が 2021 年 11 月 1 日 7:00:00 AM GMT (Unix Epoch 形式で 1635750000) に設定されます。

Command Line
curl https://api.stripe.com/v1/test_helpers/test_clocks \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d frozen_time=1635750000 \
  -d name="Annual renewal"

作成されたテストクロックの id (clock_1JGWQvIyEfDZOm8cxyhPwsoc など) をメモしておきます。これは、顧客の作成や、時間を進める際に使用します。

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

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

次のコードサンプルを使用して、Customer を作成し、それをクロックに関連付けます。その顧客のデフォルトの支払い方法を設定するのを忘れないでください (無料トライアルやそれに類似したシミュレーションをテストする場合を除く)。これには、テストカードを使用することができます。

Command Line
curl https://api.stripe.com/v1/customers \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  --data-urlencode email="jenny.rosen@example.com" \
  -d test_clock={{CLOCK_ID}} \
  -d payment_method=pm_card_visa \
  -d "invoice_settings[default_payment_method]"=pm_card_visa

デフォルトでは、List all customers (すべての顧客をリスト) エンドポイントには、テストクロックを使用する顧客は含まれていません。test_clock パラメーターを使用すると、指定されたテストクロックに関連付けられたすべての顧客のリストを取得できます。

この顧客を使用して新しいサブスクリプションを作成します。このサブスクリプションは、顧客を通じてクロックに関連付けられるため、サブスクリプションを作成するためにクロック ID を渡す必要はありません。

Command Line
curl https://api.stripe.com/v1/subscriptions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d customer={{CUSTOMER_ID}} \
  -d "items[0][price]"={{RECURRING_PRICE_ID}}

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

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

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

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

API を使用して時間を進めるには、frozen_time パラメーターを更新します。たとえば、年次更新をテストするために 2022 年 11 月 1 日に進めるには、次のようにします。

Command Line
curl https://api.stripe.com/v1/test_helpers/test_clocks/{{CLOCK_ID}}/advance \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d frozen_time=1667286000

変更を監視して処理する

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

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

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

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

Command Line
curl https://api.stripe.com/v1/test_helpers/test_clocks/{{CLOCK_ID}} \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"

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

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

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

クロックを削除する

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

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

Command Line
curl -X DELETE https://api.stripe.com/v1/test_helpers/test_clocks/{{CLOCK_ID}} \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"

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

ユースケース

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

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

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

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

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

顧客のデフォルトの支払い方法を設定するには、以下のようにします。

Command Line
curl https://api.stripe.com/v1/customers \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  --data-urlencode email="jenny.rosen@example.com" \
  -d test_clock={{CLOCK_ID}} \
  -d payment_method=pm_card_visa \
  -d "invoice_settings[default_payment_method]"=pm_card_visa

  • 顧客の支払い方法を追加した後、新しい顧客に対して月額 50 USD に設定されたサブスクリプションを作成します。そうすると、50 USD の請求書が自動的に支払われ、サブスクリプションは active になります。

  • 日付を 2 月 1 日に進めて、50 USD の請求書が作成されたことを確認します。デフォルトでは、請求書は 1 時間にわたって draft 状態で表示されます。

  • 時間を 1 時間進めて、請求書が確定され、自動的に支払われることを確認します。

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

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

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

次に、請求サイクルの途中でプランをアップグレードする顧客の比例配分 (日割り / 秒割り計算) をテストできます。たとえば、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’ にアップグレードします。

更新の保留は、サブスクリプションの更新、サブスクリプションアイテムの作成、サブスクリプションアイテムの更新の各コールで使用できます。更新を作成する際には、payment_behavior=pending_if_incomplete を設定します。以下の例では、サブスクリプションに新しい料金を追加します。proration_behavior=always_invoice が設定されているため、更新が作成されると、請求書が作成されて支払いが試行されます。

Command Line
curl https://api.stripe.com/v1/subscriptions/sub_49ty4767H20z6a \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d "payment_behavior"="pending_if_incomplete" \
  -d "proration_behavior"="always_invoice" \
  -d "items[0][id]"="si_09IkI4u3ZypJUk5onGUZpe8O" \
  -d "items[0][price]"="price_CBb6IXqvTLXp3f"

  • サブスクリプションをアップグレードした後、customer.subscription.updated Webhook イベントが作成されます。

  • 比例配分の場合は保留中の請求書アイテムも作成されます。‘basic plan’ の未使用時間に対するマイナスの比例配分 -25 USD と、残り半月における ‘premium plan’ の使用に対するプラスの比例配分 50 USD が示されます。この時点では、請求書は生成されません。

  • 日付を 2 週間進めます。ここでは日付を 2 月 1 日に設定します。サブスクリプションが循環したことが分かります。請求書が draft 状態で生成され、マイナスの比例配分、プラスの比例配分、2 月の支払い総額を含む保留中の請求書アイテムが取り込まれ、125 USD になっています。デフォルトでは、請求書は約 1 時間にわたって draft 状態で表示されます。

  • 請求書を確定するには、時間を 1 時間進めます。

トライアルをテストする

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

  1. テストクロックの作成
  2. テスト用シミュレーションの設定
  3. クロックの時間を進める
  4. 変更のモニターと処理
  5. シミュレーションの更新

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

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

サブスクリプションの作成時に次のように trial_period_days=7 引数を指定することで、無料のトライアル期間を設けて顧客のサブスクリプションを開始できます。

Command Line
curl https://api.stripe.com/v1/subscriptions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d customer=
{{CUSTOMER_ID}}
 \
  -d "items[0][price]"=
{{PRICE_ID}}
 \
  -d trial_end=1610403705
  • 7 日間無料のトライアル期間を設けてサブスクリプションを作成すると、サブスクリプションが trialing 状態で作成されます。無料トライアルであるため、$0.00 の請求書が生成されます。
  • 日付を 1 月 5 日に進めて、customer.subscription.trial_will_end のイベント通知を確認します。Stripe はトライアル終了の 3 日前に通知を送信します。この Webhook イベントを使用して、トライアルがまもなく終了することを顧客に通知できます。
  • 日付を 1 月 8 日に進めて、サブスクリプションが paid になり、50 USD の請求書が作成されたことを確認します。
  • サイクルを 1 つ (月次サブスクリプションの場合は 2 月 8 日まで) 進めて、サブスクリプションが更新されることを確認します。

制限事項

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

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

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

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

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

レート制限エラー

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

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

決済処理の注意事項

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

  1. Cancel subscription after all payment retries fail (すべての支払いの再試行が失敗した後にサブスクリプションをキャンセルする) 設定を選択します。

  2. 支払いが失敗した顧客に us_bank_account の支払い方法のタイプを追加します。

  3. その顧客でサブスクリプションを作成します。

  4. テストクロックを進めて、サブスクリプションで支払いを繰り返して回収します。

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

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

このページはお役に立ちましたか。
はいいいえ
お困りのことがございましたら 、サポートにお問い合わせください。
早期アクセスプログラムにご参加ください。
変更ログをご覧ください。
ご不明な点がございましたら、お問い合わせください。
LLM ですか？llms.txt を読んでください。
Powered by Markdoc