コンテンツにスキップ
アカウント作成/サインイン
Stripe ドキュメントのロゴ
/
アカウントを作成サインイン
概要構築済みのシステムをアップグレード
オンライン決済
概要ユースケースを見つけるManaged Payments を使用する
Elements を使用したカスタム統合の構築
対面決済
決済手段
決済シナリオ
決済以外の機能

トライアル期間を動的に更新する

決済中にサブスクリプションのトライアル期間を変更する方法をご紹介します。

プライベートプレビュー

動的トライアル更新はプライベートプレビューです。動的トライアル更新へのアクセスをリクエストする

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

ユースケース

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

Payment Intents API

Payment Intents API を使用している場合は、Subscriptions API を使用してトライアル設定を調整できます。

SDK を設定する
サーバー側

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

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

サーバー SDK を更新する
サーバー側

このベータ機能を使用するには、まず SDK を更新してプライベートプレビュー API バージョンと checkout_server_update_beta=v1 ベータ版ヘッダーを使用してください。

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 Session で年次アップセルのトライアル期間を更新します。これは、後のステップでフロントエンドから呼び出します。

セキュリティのヒント

クライアント側のコードは、ユーザーによって制御された環境で実行されます。悪意のあるユーザーは、クライアント側の検証を迂回し、リクエストを傍受して変更したり、サーバーへの新しいリクエストを作成したりすることができます。

エンドポイントを作成する際には、次のことを推奨します。

  • 汎用的にするのではなく、特定の顧客とのやり取りのためにエンドポイントを作成してください。たとえば、一般的な「更新」アクションの代わりに「年次アップグレードのトライアルを延長する」などです。特定のエンドポイントは、検証ロジックの作成と維持に役立ちます。
  • クライアントからエンドポイントに セッションデータ を直接渡さないでください。悪意のあるクライアントはリクエストデータを変更し、Checkout Session の状態を判別するための信頼できないソースにする可能性があります。代わりに、セッション 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.js
.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 でラップしてください。リクエストが成功すると、Session オブジェクトが新しいトライアル期間で更新されます。

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: actions.getSession().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 とセッションオブジェクトに反映されていることを確認します。設定されたフィールドと同じフィールドを使用してトライアルを削除します。
  • エラー処理:無効なリクエストをテストして、エラー処理が正しく機能することを確認します。
このページはお役に立ちましたか。
はいいいえ