# API と高度な使用法 ダッシュボードと API でテストクロックを使用するための高度な戦略をご紹介します。 高度なシミュレーションを実行するために、サブスクリプションとは別にシミュレーションを実行できます。このシナリオでは、まずシミュレーションを作成してから、そこにさまざまなテストケースを追加します。 完全統合型のソリューションをご希望でない場合、サブスクリプションのシミュレーションの実行について[Stripe のガイド](https://docs.stripe.com/billing/testing/test-clocks/simulate-subscriptions.md)をご覧ください。 以下の手順でテストクロックの使用を開始します。 1. [シミュレーションの作成](https://docs.stripe.com/billing/testing/test-clocks/api-advanced-usage.md#create-clock) 1. [シミュレーションを設定する](https://docs.stripe.com/billing/testing/test-clocks/api-advanced-usage.md#setup-simulation) 1. [時間を進める](https://docs.stripe.com/billing/testing/test-clocks/api-advanced-usage.md#advance-clock) 1. [変更をモニターして処理する](https://docs.stripe.com/billing/testing/test-clocks/api-advanced-usage.md#monitor-changes) 1. [シミュレーションを更新する](https://docs.stripe.com/billing/testing/test-clocks/api-advanced-usage.md#update-simulation) 1. [シミュレーションを削除する](https://docs.stripe.com/billing/testing/test-clocks/api-advanced-usage.md#delete-clock) 時間を進めること、変更を監視すること、シミュレーションを更新することは、さまざまなケースのテストに必要な回数だけ実行できます。 ## シミュレーションを作成して時刻を設定する シミュレーションでは、クロックをオブジェクトとして使用し、クロックの時刻を参照できます。シミュレーションを開始するには、クロックを作成し、テストの開始点である凍結時刻を設定します。凍結時刻は過去または将来の時点に設定しますが、設定後は時刻を進めることのみが可能です。 #### ダッシュボード [サンドボックスを作成](https://docs.stripe.com/sandboxes/dashboard/manage.md)して、シミュレーションを開始します。 1. **Billing** タブの**サブスクリプション**[セクション](https://dashboard.stripe.com/test/subscriptions)に移動します。 1. バナーで[シミュレーション](https://dashboard.stripe.com/test/test-clocks)のリンクをクリックします。 1. **新しいシミュレーション**をクリックします。 1. **新しいシミュレーションの作成**モーダルで、シミュレーションの名前を入力します。`Annual renewal` や `Free trial` など、この名前を使用して、テストするシミュレーションを説明することができます。 1. シミュレーションの凍結時間を設定します。 #### API API では、[frozen_time](https://docs.stripe.com/api/test_clocks/object.md#test_clock_object-frozen_time) フィールドに Unix Epoch のタイムスタンプとして時刻を指定します。この例では、`Annual renewal` クロックの凍結時刻が 2021 年 11 月 1 日 7:00:00 AM GMT (Unix Epoch 形式で `1635750000`) に設定されます。 ```curl curl https://api.stripe.com/v1/test_helpers/test_clocks \ -u "<>:" \ -d frozen_time=1635750000 \ -d "name=Annual renewal" ``` 作成されたテストクロックの `id` (`clock_1JGWQvIyEfDZOm8cxyhPwsoc` など) をメモしておきます。これは、顧客の作成や、時間を進める際に使用します。 ## シミュレーションを設定する 次に、シミュレーションのためのテストケースを設定します。まず顧客を作成してから、その顧客のためのサブスクリプションを作成する必要があります。 #### ダッシュボード ダッシュボードでシミュレーション用の顧客を作成するには、以下のようにします。 1. [Simulations](https://dashboard.stripe.com/test/test-clocks) ページに移動して、シミュレーションを見つけます。 1. **追加** > **顧客を追加**をクリックします。 シミュレーション中は、既存の顧客を選択できません。シミュレーションごとに新しい顧客を 3 人まで追加できます。 オプションで、顧客の名前、メールアドレス、請求情報などの利用可能なプロパティを入力できますが、いずれも必須ではありません。無料トライアルのテストなどの一部のシミュレーションでは、請求情報を事前に収集する必要はありません。 次に、顧客に 3 件までのサブスクリプションまたはサブスクリプションのスケジュールを作成できます。ダッシュボードを使用して顧客のサブスクリプションを作成するには、以下のようにします。 1. [Simulations](https://dashboard.stripe.com/test/test-clocks) のページに移動して、シミュレーションを見つけます。 1. **追加** > **サブスクリプションを追加**をクリックして、ドロップダウンメニューから顧客を選択または検索します。また、顧客ページで**アクション** > **サブスクリプションを作成**をクリックして、顧客をサブスクリプションに追加することもできます。 1. **料金体系**セクションで継続支払いの商品と価格を選択します。 1. **サブスクリプションスケジュール**では、サブスクリプションの開始日と終了日、および請求期間の開始日を定義します。 1. 支払いの回収方法を選択します。 - 請求期間の開始時に顧客に請求する場合は、**登録されている決済手段に自動的に請求する**を選択します。 - 顧客に後から請求書を送付するには、**手動支払い用の請求書を顧客にメールで送付する**を選択します。 1. **テストのサブスクリプションを開始**をクリックして、サブスクリプションと請求期間を開始します。 #### API > #### Accounts v2 API を使用した顧客の表現 > > Accounts v2 API は、Connect ユーザー向けには GA、その他の Stripe ユーザー向けには公開プレビューとして提供されています。すべての Stripe ユーザーは [Dashboard](https://dashboard.stripe.com/settings/connect/platform-setup) で Accounts v2 を有効にできます。ただし、Accounts v2 API の呼び出し時には、プレビューユーザーは[プレビューバージョンを指定](https://docs.stripe.com/api-v2-overview.md#sdk-and-api-versioning)する必要があります。 > > ほとんどのユースケースでは、[Customer](https://docs.stripe.com/api/customers.md) オブジェクトを使用するのではなく、[顧客を顧客設定の Account オブジェクトとしてモデル化する](https://docs.stripe.com/connect/use-accounts-as-customers.md)ことをお勧めします。 次のコードサンプルを使用して、顧客を作成し、それをクロックに関連付けます。顧客のデフォルトの決済手段を設定することを忘れないでください (無料トライアルやそれに類似したシミュレーションをテストする場合を除く)。これには、[テストカード](https://docs.stripe.com/testing.md#cards)を使用することができます。 #### Accounts v2 デフォルトの決済手段を設定した顧客構成の `Account` を作成するには、まず `Account` を作成し、その後に決済手段を `Account` へ紐づける必要があります。`Account` の作成時にデフォルトの決済手段を指定することはできません。 テストクロック付きで v2 の `Account` を使用するには、`Account` に `customer` 設定を最初に追加する際に、テストクロック ID を設定する必要があります。この設定は `Account` の作成時または更新時に追加できますが、後から追加してテストクロック ID を設定することはできません。 `PaymentMethod` オブジェクトを生成し、それを `Account` に関連付けるには、決済手段の詳細を使用して [SetupIntent](https://docs.stripe.com/api/setup_intents/create.md) または [PaymentIntent](https://docs.stripe.com/api/payment_intents/create.md) を作成し、`customer_account` パラメータとして `Account` ID を指定します。 ```curl curl https://api.stripe.com/v1/setup_intents \ -u "<>:" \ -d confirm=true \ -d customer_account=acct_1234 \ -d "mandate_data[customer_acceptance][accepted_at]=1678942624" \ -d "mandate_data[customer_acceptance][type]=offline" \ -d "payment_method_data[billing_details][address][line1]=234 Oak Street" \ -d "payment_method_data[billing_details][address][postal_code]=12345" \ --data-urlencode "payment_method_data[billing_details][email]=jenny.rosen@example.com" \ -d "payment_method_data[billing_details][name]=Jenny Rosen" \ -d "payment_method_data[type]=us_bank_account" \ -d "payment_method_data[us_bank_account][account_holder_type]=individual" \ --data-urlencode "payment_method_data[us_bank_account][account_number]=********6789" \ -d "payment_method_data[us_bank_account][routing_number]=110000000" \ -d "payment_method_options[us_bank_account][verification_method]=automatic" \ -d "payment_method_types[]=us_bank_account" \ --data-urlencode "return_url=https://www.stripe.com" ``` 返される `SetupIntent` または `PaymentIntent` には、生成された `PaymentMethod` オブジェクトの ID が [payment_method](https://docs.stripe.com/api/setup_intents/object.md#setup_intent_object-payment_method) プロパティに含まれています。 次に、顧客構成の `Account` を更新し、[default_payment_method](https://docs.stripe.com/api/v2/core/accounts/update.md#v2_update_accounts-configuration-customer-billing-default_payment_method) パラメーターとして `PaymentMethod` ID を指定します。 ```curl curl -X POST https://api.stripe.com/v2/core/accounts/acct_1234 \ -H "Authorization: Bearer <>" \ -H "Stripe-Version: 2026-03-25.preview" \ --json '{ "configuration": { "customer": { "billing": { "default_payment_method": "pm_1234" } } }, "include": [ "configuration.customer" ] }' ``` #### Customers v1 [顧客を作成](https://docs.stripe.com/api/customers/create.md)し、`test_clock` パラメータをテストクロック ID に設定し、`payment_method` パラメータと `invoice_settings.default_payment_method` パラメータの両方に `PaymentMethod` の ID を設定します。 ```curl curl https://api.stripe.com/v1/customers \ -u "<>:" \ --data-urlencode "email=jenny.rosen@example.com" \ -d test_clock={{CLOCK_ID}} \ -d payment_method=pm_1234 \ -d "invoice_settings[default_payment_method]=pm_1234" ``` [List all customers](https://docs.stripe.com/api/customers/list.md) エンドポイントは、[test_clock](https://docs.stripe.com/api/customers/list.md#list_customers-test_clock) パラメータでテストクロック ID を指定しない限り、テストクロックに関連付けられた顧客を返しません。 この顧客を使用して[新しいサブスクリプションを作成](https://docs.stripe.com/billing/subscriptions/build-subscriptions.md)します。このサブスクリプションは、顧客を通じてクロックに関連付けられるため、サブスクリプションを作成するためにクロック ID を渡す必要はありません。 #### Accounts v2 ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -d "customer_account={{CUSTOMERACCOUNT_ID}}" \ -d "items[0][price]={{RECURRING_PRICE_ID}}" ``` #### Customers v1 ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d "items[0][price]={{RECURRING_PRICE_ID}}" ``` 顧客とサブスクリプションの両方が、[最初のステップ](https://docs.stripe.com/billing/testing/test-clocks/api-advanced-usage.md#create-clock)で作成したシミュレーションに関連付けられます。 ## シミュレーションの時間を進める シミュレーションを作成してテストケースを設定した後で、シミュレーションの時間を進めます。初めて時間を進める場合は、開始時に設定した元の凍結時刻から時間を進めることになります。時間を進めることで、サブスクリプションの終了時、更新時、またはその他の変化が発生したとき（無料トライアルから有料のサブスクリプションへのアップグレードなど）に、システムがどのように機能するかを確認できます。 最大 2 つの間隔で時間を進めます。期間の長さは、サブスクリプションに関連付けられた最短のサービス期間 (継続価格によって決まります) に基づきます。たとえば、月次のサブスクリプションでは、一度に最大 2 カ月までしか時間を進めることができません。サブスクリプションやサブスクリプションスケジュールを設定していない場合は、最初の凍結日時から最大 2 年間進めることができます。 #### ダッシュボード ダッシュボードで時間を進めるには、以下のようにします。 1. [Simulations](https://dashboard.stripe.com/test/test-clocks) ページに移動して、シミュレーションを見つけます。 1. **時間を進める**をクリックします。 1. カレンダーモーダルを使用して、クロックを先に進める日付を選択します。 1. **進める**をクリックします。 #### API API を使用して時間を進めるには、`frozen_time` パラメーターを更新します。たとえば、年次更新をテストするために 2022 年 11 月 1 日に進めるには、次のようにします。 ```curl curl https://api.stripe.com/v1/test_helpers/test_clocks/{{CLOCK_ID}}/advance \ -u "<>:" \ -d frozen_time=1667286000 ``` ## 変更を監視して処理する API リクエストまたは Dashboard 操作が成功すると、指定された時間に進むまでに数秒かかります。シミュレーションのステータスがいつ変更されたかを確認するには、Webhook を使用してイベント通知をリッスンするか、Clock オブジェクトをポーリングします。Dashboard にも変更が反映されます。 たとえば、[請求書ページ](https://dashboard.stripe.com/test/invoices)に移動して、請求書が作成されたか、サブスクリプションに対して支払われたかを確認できます。 [Webhook](https://docs.stripe.com/webhooks.md) を使用している場合には、以下のイベント通知をリッスンします。本番環境に移行する前に、システムが、以下に記載されたものに加え、その他の[請求固有のイベント通知](https://docs.stripe.com/billing/subscriptions/webhooks.md)も正しく処理することを確認してください。 | イベント | 説明 | | ----------------------------------- | ------------------------------ | | `test_helpers.test_clock.advancing` | クロックは進み始めましたが、指定された時間に達していません。 | | `test_helpers.test_clock.ready` | クロックは、指定された時間への進行を終了しました。 | Clock のステータスをポーリングするには、Clock を ID で [取得して](https://docs.stripe.com/api/test_clocks/retrieve.md)、`status` を調べます。 ```curl curl https://api.stripe.com/v1/test_helpers/test_clocks/{{CLOCK_ID}} \ -u "<>:" ``` ## シミュレーションを更新する 続けて変更を加え、以下のようなシミュレーションに合わせて[クロックを進める](https://docs.stripe.com/billing/testing/test-clocks/api-advanced-usage.md#advance-clock)ことができます。 - [顧客の残高](https://docs.stripe.com/billing/customer/balance.md)を追加する。 - サイクルの途中でアップグレードする。 - [1 回限りの請求書アイテムを追加する](https://docs.stripe.com/billing/invoices/subscription.md#adding-upcoming-invoice-items)。 それぞれの更新の後、再び[変更を監視](https://docs.stripe.com/billing/testing/test-clocks/api-advanced-usage.md#monitor-changes)します。テストケースに対応するために、必要に応じて何回も繰り返します。 ## シミュレーションを削除する シミュレーションは、作成から 30 日経過すると自動的に削除されますが、テストの終了後に削除してテスト環境を整然と保つことができます。 #### ダッシュボード ダッシュボードでシミュレーションとすべての関連するテストオブジェクトを削除するには、次のようにします。 1. [シミュレーション](https://dashboard.stripe.com/test/test-clocks)ページに移動して、シミュレーションを見つけます。 1. **シミュレーションを終了**をクリックします。 1. 確認モーダルで、**終了**をクリックします。 #### API API でクロックとすべての関連するテストオブジェクトを削除するには、次のようにします。 ```curl curl -X DELETE https://api.stripe.com/v1/test_helpers/test_clocks/{{CLOCK_ID}} \ -u "<>:" ``` シミュレーションを削除すると、クロックに関連付けられたテスト用の顧客も削除され、そのサブスクリプションがキャンセルされます。シミュレーションはサンドボックスのみで使用できるため、クロックを削除しても本番環境のオブジェクトは何も削除されません。 ## ユースケース いずれの場合も、まず新しいシミュレーションを作成します。 1. [シミュレーションの作成](https://docs.stripe.com/billing/testing/test-clocks/api-advanced-usage.md#create-clock) 1. [シミュレーションを設定する](https://docs.stripe.com/billing/testing/test-clocks/api-advanced-usage.md#setup-simulation) 1. [時間を進める](https://docs.stripe.com/billing/testing/test-clocks/api-advanced-usage.md#advance-clock) 1. [変更をモニターして処理する](https://docs.stripe.com/billing/testing/test-clocks/api-advanced-usage.md#monitor-changes) 1. [シミュレーションを更新する](https://docs.stripe.com/billing/testing/test-clocks/api-advanced-usage.md#update-simulation) ### サブスクリプションの更新をテストする 50 USD /月のサブスクリプションが正しく更新されることをテストしたいとします。 - シミュレーションを作成し、その `frozen_time` を January 1 に設定します。 - 顧客を追加して、その顧客の支払い方法を追加します。 #### ダッシュボード ダッシュボードで顧客の支払い方法を追加するには、以下のようにします。 1. 顧客のアカウントページで、**支払い方法**セクションの**追加 > カードを追加**をクリックします。 1. 決済情報を入力します。ここでは、4242424242424242 [テストカード](https://docs.stripe.com/testing.md#cards)を使用します。 1. モーダルの**カードを追加**をクリックします。 #### API #### Accounts v2 デフォルトの決済手段を設定した顧客構成の `Account` を作成するには、まず `Account` を作成し、その後に決済手段を `Account` へ紐づける必要があります。`Account` の作成時にデフォルトの決済手段を指定することはできません。 テストクロック付きで v2 の `Account` を使用するには、`Account` に `customer` 設定を最初に追加する際に、テストクロック ID を設定する必要があります。この設定は `Account` の作成時または更新時に追加できますが、後から追加してテストクロック ID を設定することはできません。 `PaymentMethod` オブジェクトを生成し、それを `Account` に関連付けるには、決済手段の詳細を使用して [SetupIntent](https://docs.stripe.com/api/setup_intents/create.md) または [PaymentIntent](https://docs.stripe.com/api/payment_intents/create.md) を作成し、`customer_account` パラメータとして `Account` ID を指定します。 ```curl curl https://api.stripe.com/v1/setup_intents \ -u "<>:" \ -d confirm=true \ -d customer_account=acct_1234 \ -d "mandate_data[customer_acceptance][accepted_at]=1678942624" \ -d "mandate_data[customer_acceptance][type]=offline" \ -d "payment_method_data[billing_details][address][line1]=234 Oak Street" \ -d "payment_method_data[billing_details][address][postal_code]=12345" \ --data-urlencode "payment_method_data[billing_details][email]=jenny.rosen@example.com" \ -d "payment_method_data[billing_details][name]=Jenny Rosen" \ -d "payment_method_data[type]=us_bank_account" \ -d "payment_method_data[us_bank_account][account_holder_type]=individual" \ --data-urlencode "payment_method_data[us_bank_account][account_number]=********6789" \ -d "payment_method_data[us_bank_account][routing_number]=110000000" \ -d "payment_method_options[us_bank_account][verification_method]=automatic" \ -d "payment_method_types[]=us_bank_account" \ --data-urlencode "return_url=https://www.stripe.com" ``` 返される `SetupIntent` または `PaymentIntent` には、生成された `PaymentMethod` オブジェクトの ID が [payment_method](https://docs.stripe.com/api/setup_intents/object.md#setup_intent_object-payment_method) プロパティに含まれています。 次に、顧客構成の `Account` を更新し、[default_payment_method](https://docs.stripe.com/api/v2/core/accounts/update.md#v2_update_accounts-configuration-customer-billing-default_payment_method) パラメーターとして `PaymentMethod` ID を指定します。 ```curl curl -X POST https://api.stripe.com/v2/core/accounts/acct_1234 \ -H "Authorization: Bearer <>" \ -H "Stripe-Version: 2026-03-25.preview" \ --json '{ "configuration": { "customer": { "billing": { "default_payment_method": "pm_1234" } } }, "include": [ "configuration.customer" ] }' ``` #### Customers v1 [顧客を作成](https://docs.stripe.com/api/customers/create.md)し、`test_clock` パラメータをテストクロック ID に設定し、`payment_method` パラメータと `invoice_settings.default_payment_method` パラメータの両方に `PaymentMethod` の ID を設定します。 ```curl curl https://api.stripe.com/v1/customers \ -u "<>:" \ --data-urlencode "email=jenny.rosen@example.com" \ -d test_clock={{CLOCK_ID}} \ -d payment_method=pm_1234 \ -d "invoice_settings[default_payment_method]=pm_1234" ``` [List all customers](https://docs.stripe.com/api/customers/list.md) エンドポイントは、[test_clock](https://docs.stripe.com/api/customers/list.md#list_customers-test_clock) パラメータでテストクロック ID を指定しない限り、テストクロックに関連付けられた顧客を返しません。 - 顧客の支払い方法を追加した後、新しい顧客に対して月額 50 USD に設定されたサブスクリプションを作成します。そうすると、50 USD の請求書が自動的に支払われ、サブスクリプションは `active` になります。 - 日付を 2 月 1 日に進めて、50 USD の請求書が作成されたことを確認してください。デフォルトでは、請求書は [1 時間](https://docs.stripe.com/billing/invoices/subscription.md#adding-draft-invoice-items) は `draft` ステータスで表示されます。 - 時間を 1 時間進めて、請求書が確定され、自動的に支払われることを確認します。 ### 比例配分が適用されるサイクル途中のアップグレードをテストする 2 つの製品があるとします。1 つの製品は 50 USD /月 (基本プラン) で、もう 1 つは 100 USD /月 (「プレミアムプラン」) です。この場合、請求期間の途中で基本プランからプレミアムプランにアップグレードする顧客の比例配分をテストしたい場合があります。この状況をシミュレートするには以下のようにします。 - シミュレーションを作成し、`frozen_time` を January 1 に設定します。 - 顧客を作成して支払い方法を追加します。ここでは、4242424242424242 [テストカード](https://docs.stripe.com/testing.md#cards)を使用します。 - ‘basic plan’ の月額 50 USD のサブスクリプションを作成します。これを完了すると、月額 50 USD の請求書が作成され、確定されて自動的に支払われたことが分かります。 - 日付を 2 週間進めます。ここでは日付を 1 月 16 日に設定します。 - サブスクリプションを月額 100 USD の ‘premium plan’ にアップグレードします。 #### ダッシュボード ダッシュボードを使用してサブスクリプションをアップグレードするには、以下のようにします。 1. 顧客のアカウントページまたはサブスクリプションの詳細ページで、サブスクリプションに関連するオーバーフローメニュー (⋯) をクリックして、**サブスクリプションを更新**を選択します。 1. 必要な変更を行います。 1. 右上隅にある**サブスクリプションを更新**をクリックして、変更を適用します。 #### API 更新の保留は、[サブスクリプションの更新](https://docs.stripe.com/api/subscriptions/update.md)、[サブスクリプションアイテムの作成](https://docs.stripe.com/api/subscription_items/create.md)、[サブスクリプションアイテムの更新](https://docs.stripe.com/api/subscription_items/update.md)の各コールで使用できます。更新を作成する際には、`payment_behavior=pending_if_incomplete` を設定します。以下の例では、サブスクリプションに新しい料金を追加します。`proration_behavior=always_invoice` が設定されているため、更新が作成されると、請求書が作成されて支払いが試行されます。 #### curl ```bash curl https://api.stripe.com/v1/subscriptions/sub_49ty4767H20z6a \ -u <>: \ -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](https://docs.stripe.com/api/events/types.md#event_types-customer.subscription.updated) Webhook イベントが作成されます。 - 比例配分の場合は保留中の請求書アイテムも作成されます。‘basic plan’ の未使用時間に対するマイナスの比例配分 -25 USD と、残り半月における ‘premium plan’ の使用に対するプラスの比例配分 50 USD が示されます。この時点では、請求書は生成されません。 - 日付を 2 週間進めます。ここでは日付を 2 月 1 日に設定します。サブスクリプションが次の請求期間に移行したことが確認できます。請求書が `draft` 状態で生成され、未確定の請求明細が反映されます。これには、マイナスの日割り料金、プラスの日割り料金、2 月分の月額料金が含まれ、合計 125 USD となります。デフォルトでは、請求書は約 [1 時間](https://docs.stripe.com/billing/invoices/subscription.md#adding-draft-invoice-items)にわたって `draft` のステータスで表示されます。 - 請求書を確定するには、時間を 1 時間進めます。 ### トライアルをテストする たとえば、顧客に決済を開始する前に 7 日間のトライアルで商品を無料で試してもらい、決済情報は事前に徴収するとします。テストクロックを使用してこの状況をシミュレーションするには、以下のようにします。 - 新しいシミュレーションを作成し、`frozen_time` を January 1 に設定します。 - 顧客を追加して支払い方法を含めます。ここでは、4242424242424242 の[テストカード](https://docs.stripe.com/testing.md#cards)を使用します。 - サブスクリプションを作成して、7 日間無料のトライアル期間を追加します。 #### ダッシュボード ダッシュボードから既存のサブスクリプションにトライアル期間を追加するには、以下を行います。 変更するサブスクリプションを探します。 1. **アクション**をクリックします。 1. **サブスクリプションを更新**をクリックします。 1. **無料トライアルを追加**をクリックして、**無料トライアルの日数**フィールドに 7 を入力します。 1. **サブスクリプションを更新**をクリックします。 #### API サブスクリプションの作成時に次のように `trial_period_days=7` 引数を指定することで、無料のトライアル期間を設けて顧客のサブスクリプションを開始できます。 #### Accounts v2 ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -d "customer_account={{CUSTOMERACCOUNT_ID}}" \ -d "items[0][price]={{PRICE_ID}}" \ -d trial_end=1610403705 ``` #### Customers v1 ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d "items[0][price]={{PRICE_ID}}" \ -d trial_end=1610403705 ``` - サブスクリプションを 7 日間の無料トライアル期間付きで作成すると、サブスクリプションは `trialing` のステータスで作成されます。無料トライアルのため、請求額 0.00 USD の請求書が生成されます。 - 日付を 1 月 5 日に進めて、[customer.subscription.trial_will_end](https://docs.stripe.com/api/events/types.md#event_types-customer.subscription.trial_will_end) のイベント通知を確認します。Stripe はトライアル終了の 3 日前に通知を送信します。この Webhook イベントを使用して、トライアルがまもなく終了することを顧客に通知できます。 - 日付を 1 月 8 日に進めて、サブスクリプションが `paid` になり、50 USD の請求書が作成されたことを確認します。 - サイクルを 1 つ (月次サブスクリプションの場合は 2 月 8 日まで) 進めて、サブスクリプションが更新されることを確認します。 ## 制限事項 シミュレーションできるのは以下までです。 - 3 名の顧客 - 顧客ごとに 3 件のサブスクリプション ([スケジュール済みサブスクリプション](https://docs.stripe.com/billing/subscriptions/subscription-schedules.md)を含む) - 顧客に関連付けられていない 10 件の見積もり ### すべての結果のリストで省略されたテストクロックオブジェクト API の一覧取得メソッド ([List Invoices](https://docs.stripe.com/api/invoices/list.md) など) は、クエリ句を指定しない限り、テストクロックによって生成されたオブジェクトを返しません。必要なクエリパラメーターはリソースによって異なるため、API リファレンスの各一覧メソッドの説明を確認してください。 たとえば、`GET /v1/invoices` はテストクロックで生成された請求書を返しませんが、`customer:"cus_123"` のようなクエリ句を付けた `GET /v1/invoices` は、テストクロックで生成されたものも含め、その顧客のすべての請求書を返します。 同様に、この例でテストクロック ID を指定して、そのテストクロックに関連するすべての請求書を取得することも、サブスクリプション ID を指定して、テストクロックによって生成された請求書を含む、そのサブスクリプションに対して請求されたすべての請求書を返すこともできます。 ### レート制限エラー テストクロックが設定されたサブスクリプションに対して複数回の更新を行うと、Stripe からレート制限エラーが返されることがあります。サブスクリプションはテストクロックの時刻まで凍結されているため、その時刻までのすべての API リクエストがカウントされ、レート制限がトリガーされる可能性があります。 これを回避するには、サブスクリプションで追加の API リクエストを行う前に、シミュレーションされたクロックの時刻を数分進めます。 Subscriptions API は、最大リクエスト数を次のように制限します。 - 新規請求書10件/分 (1サブスクリプション) - 新規請求書20件/日 (1サブスクリプション) - 数量更新200件/時間 (1サブスクリプション) ### 決済処理の注意事項 現在、テストクロックの進行は銀行口座引き落としによる支払いの回収 (支払い方法のタイプ `us_bank_account` など) に対応していません。Stripe は、テストクロックが時間を進めた後で支払いを回収します。支払いの失敗をテストするには、次の手順を実行します。 1. **Cancel subscription after all payment retries fail (すべての支払いの再試行が失敗した後にサブスクリプションをキャンセルする)** 設定を選択します。 1. 支払いが失敗した顧客に `us_bank_account` の支払い方法のタイプを追加します。 1. その顧客でサブスクリプションを作成します。 1. テストクロックを進めて、サブスクリプションで支払いを繰り返して回収します。 テスト用 Clock を進めた後も、サブスクリプションのステータスは `active` のままです。これは、テスト Clock の時間進行中に支払いの回収が行われなかったことを示しています。また、サブスクリプションは `payment_failed` になったことで `canceled` のステータスに移行したわけではありません。 `invoice.payment_failed` イベントを受信して、遅延が生じたサブスクリプションのステータスと請求書に対する支払いを監視します。`customer.subscription.deleted` イベントは、サブスクリプションのステータスが `canceled` に設定されたことを示しています。