Dynamically update trial durations

Learn how to modify subscription trial periods during checkout.

Private preview

Dynamic trial updates is in private preview. Request access to dynamic trial updates.

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

ユースケース

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

Payment Intents API

If you use the Payment Intents API, you can use the Subscriptions API to adjust trial settings.

Set up the SDK
Server-side

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

Update the server SDK
Server-side

To use this beta, first update your SDK to use the private preview API version and the checkout_server_update_beta=v1 beta version header.

Dynamically update trial durations
Server-side

Create an endpoint on your server to update the trial duration for a yearly upsell on the Checkout Session. You call this from the front end in a later step.

セキュリティのヒント

Client-side code runs in an environment that’s controlled by the user. A malicious user can bypass your client-side validation, intercept and modify requests, or create new requests to your server.

When creating an endpoint, we recommend the following:

Create endpoints for specific customer interactions instead of making them generic. For example, “extend trial for yearly upgrade” instead of a general “update” action. Specific endpoints can help with writing and maintaining validation logic.
Don’t pass session data directly from the client to your endpoint. Malicious clients can modify request data, making it an unreliable source for determining the Checkout Session state. Instead, pass the session ID to your server and use it to securely retrieve the data from the Stripe API.

You can update trial durations using either:

trial_period_days: An integer that represents the number of days for the trial period, or an empty string to remove the trial.
trial_end: A Unix timestamp that represents when the trial should end, or an empty string to remove the trial.

Keep in mind the following:

The trial_period_days and trial_end parameters are mutually exclusive. You can only specify one of them in a single update request.
When removing a trial, use the same field that it was set with. You can only use trial_period_days: "" to remove a trial set with trial_period_days. You can only use trial_end: "" to remove a trial set with trial_end.

Update the client SDK
Client-side

Initialize Stripe.js with the custom_checkout_server_updates_1 beta header.

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

Request server updates
Client-side

From your front end, send an update request to your server and wrap it in runServerUpdate. A successful request updates the Session object with the new trial duration.

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;
  });

Test the integration

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

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

注

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

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

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

注