コンテンツにスキップ
アカウントを作成
または
サインイン
Stripe ドキュメントのロゴ
/
アカウントを作成
サインイン
概要構築済みのシステムをアップグレード
オンライン決済
概要ユースケースを見つけるManaged Payments
決済ページを構築
決済手段
支払いインターフェイス
決済シナリオ
店頭支払い
決済にとどまらない機能

トライアル期間を動的に更新する非公開プレビュー

決済時に加えられた変更に応じてトライアル期間を更新します。

非公開プレビュー版

この機能はプライベートプレビュー版です。動的なトライアル更新の利用をリクエストします。

サブスクリプションの Checkout セッションのトライアル期間を動的に更新する方法をご紹介します。

ユースケース

  • 動的なトライアル管理:プロモーション条件や顧客のアクションに基づいてトライアルを追加または削除します。
  • アップセル時のトライアル期間の延長:顧客が上位プランにアップグレードする際に、トライアル期間を延長します(例: 月額の 7 日間を年額では 14 日間に延長)。

SDK を設定する
サーバー側

Stripe の公式ライブラリを使用して、アプリケーションから Stripe API にアクセスします。

Command Line
Ruby
Python
PHP
Node
.NET
Go
Java
No results
gem install stripe -v 15.1.0-beta.2

サーバー SDK の更新
サーバー側

このベータ版を使用するには、まず非公開プレビュー版の API バージョンと checkout_server_update_beta=v1 のベータ版ヘッダーを使用するように SDK を更新します。

Ruby
Python
PHP
Node
.NET
Go
Java
No results
# Set your secret key. Remember to switch to your live secret key in production.
# See your keys here: https://dashboard.stripe.com/apikeys
Stripe.api_key = 
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'

Stripe.api_version = '2025-03-31.preview; checkout_server_update_beta=v1;'

トライアル期間を動的に更新する
サーバー側

サーバー上に新しいエンドポイントを作成して、Checkout セッションでの年額アップセルのトライアル期間を更新します。これは、後のステップでフロントエンドから呼び出します。

セキュリティのヒント

クライアント側のコードは、ユーザーが完全に制御できる環境で実行されます。悪意のあるユーザーは、クライアント側の検証をバイパスしたり、リクエストを傍受して変更したり、サーバーに対してまったく新しいリクエストを作成したりする可能性があります。

エンドポイントを設計する際は、以下を考慮することをお勧めします。

  • エンドポイントは過度に汎用的にするのではなく、特定の顧客とのやり取りに対応するように設計します (たとえば、一般的な「更新」アクションではなく、「年額アップグレードのトライアル期間の延長」など)。具体的なエンドポイントは目的がわかりやすく、検証ロジックの記述と維持が簡単になります。
  • セッションデータをクライアントからエンドポイントに直接渡さないようにしてください。悪意のあるクライアントがリクエストデータを変更する可能性があり、Checkout セッションの状態を判断するためのソースとしての信頼性が低くなってしまいます。代わりに、セッション ID をサーバーに渡し、それを使用して Stripe の API からデータを安全に取得します。

トライアル期間は、次のいずれかを使用して更新できます。

  • trial_period_days:トライアル期間の日数を表す整数、またはトライアルを削除する空の文字列
  • trial_end:トライアルの終了日を表す Unix タイムスタンプ、またはトライアルを削除するための空の文字列

次の説明を参考にしてください。

  • trial_period_days パラメーターと trial_end パラメーターは相互排他的です。1 回の更新リクエストで指定できるのは、そのうちの 1 つだけです。
  • トライアルを削除する場合は、トライアルに設定されたフィールドと同じフィールドを使用します。trial_period_days が設定されたトライアルセットは、trial_period_days: "" を指定してのみ削除できます。trial_end が設定されたトライアルセットは、trial_end: "" を指定してのみ削除できます。
Ruby
Python
PHP
Node
.NET
Go
Java
No results
require 'sinatra'
require 'json'
require 'stripe'

set :port, 4242

# Set your secret key. Remember to switch to your live secret key in production.
# See your keys here: https://dashboard.stripe.com/apikeys
Stripe.api_key = 
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'

Stripe.api_version = '2025-03-31.preview; checkout_server_update_beta=v1;'

post '/extend-trial-for-yearly' do
  content_type :json
  request.body.rewind
  request_data = JSON.parse(request.body.read)

  checkout_session_id = request_data['checkout_session_id']

  if checkout_session_id.nil?
    status 400
    return {
      type: 'error',
      message: 'We could not process your request. Please try again later.'
    }.to_json
  end

  begin
    # 1. Retrieve the current session to validate it's a subscription
    session = Stripe::Checkout::Session.retrieve(checkout_session_id)

    unless session.mode == 'subscription'
      status 400
      return {
        type: 'error',
        message: 'Trial updates are only available for subscription sessions.'
      }.to_json
    end

    # 2. Update the Checkout Session with extended trial duration
    Stripe::Checkout::Session.update(checkout_session_id, {
      subscription_data: {
        trial_period_days: 14,
      }
    })

    # 3. Return success response
    { type: 'success' }.to_json
  rescue Stripe::StripeError
    # Handle Stripe errors with a generic error message
    status 400
    {
      type: 'error',
      message: 'We couldn't process your request. Please try again later.'
    }.to_json
  rescue StandardError
    # Handle unexpected errors
    status 500
    {
      type: 'error',
      message: 'Something went wrong on our end. Please try again later.'
    }.to_json
  end
end

クライアント SDK の更新
クライアント側

custom_checkout_server_updates_1 ベータヘッダーを使用して stripe.js を初期化します。

checkout.js
const stripe = Stripe(
'pk_test_TYooMQauvdEDq54NiTphI7jx'
, {
  betas: ['custom_checkout_server_updates_1'],
});

サーバー更新の呼び出し
クライアント側

フロントエンドから更新をトリガーするには、サーバーにリクエストを送信し、それを runServerUpdate でラップします。リクエストが成功すると、セッションオブジェクトが新しいトライアル期間で更新されます。

index.html
<button id="extend-trial-yearly">
  Upgrade to a yearly subscription and get an extended trial
</button>
checkout.js
document.getElementById('extend-trial-yearly')
  .addEventListener("click", async (event) => {
    const updateCheckout = () => {
      return fetch("/extend-trial-for-yearly", {
        method: "POST",
        headers: {
          "Content-type": "application/json",
        },
        body: JSON.stringify({
          checkout_session_id: checkout.session().id,
        })
      });
    };

    const response = await checkout.runServerUpdate(updateCheckout);
    if (!response.ok) {
      // Handle error state
      return;
    }

    // Update UI to reflect the extended trial
    event.target.textContent = "Trial extended to 14 days!";
    event.target.disabled = true;
  });

実装のテスト

実装内容をテストして、トライアル期間の更新が正しく機能していることを確認します。

  1. 初回トライアル期間を指定してサブスクリプションの Checkout セッションを作成します。
  2. 作成した UI 要素を操作して、サーバーエンドポイントをトリガーします。
  3. トライアル期間が Checkout セッションで正しく更新されていることを確認します。
  4. 決済を完了して、サブスクリプションが正しいトライアル設定で作成されていることを確認します。

注

テストする際は、Stripe のテスト環境を使用して本番サブスクリプションが作成されないようにします。トライアル期間の変更を確認するには、Checkout Session オブジェクトまたは作成されたサブスクリプションを調べます。

一般的なシナリオのテスト

  • トライアルの延長:7 日間のトライアルを開始した後、期間を 14 日間に延長し、その変更が UI と セッションオブジェクトに反映されていることを確認します。
  • 既存のトライアルの削除:7 日間のトライアルを開始した後、トライアルを削除し、その変更が UI とセッションオブジェクトに反映されていることを確認します。設定されたフィールドと同じフィールドを使用してトライアルを削除します。
  • エラー処理:無効なリクエストをテストして、エラー処理が正しく機能することを確認します。
このページはお役に立ちましたか。
はいいいえ