Skip to content
Create account
 or
Sign in
The Stripe Docs logo
/
Create account
Sign in
OverviewUpgrade your integration
Online payments
OverviewFind your use caseUse Managed Payments
Payment Methods
Payment interfaces
Payment scenarios
In-person payments
Beyond payments

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.

Learn how to dynamically update trial durations on subscription Checkout Sessions.

Use cases

  • Dynamic trial management: Add or remove trials based on promotional conditions or customer actions.
  • Extend trials for upsells: Offer longer trial periods when customers upgrade to higher-tier plans (for example. 7 days for monthly gets extended to 14 days for yearly).

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

Use our official libraries to access the Stripe API from your application:

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

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.

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;'

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.

Security tip

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.
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

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

Test your integration to ensure trial duration updates work correctly:

  1. Create a subscription Checkout Session with an initial trial period.
  2. Trigger your server endpoint by interacting with the UI element you created.
  3. Verify the trial duration is updated correctly in the Checkout Session.
  4. Complete the checkout to ensure the subscription is created with the correct trial settings.

Note

When testing, use Stripe’s test mode to avoid creating live subscriptions. You can verify the trial duration changes by inspecting the Checkout Session object or the created subscription.

Common testing scenarios

  • Trial extension: Start with a 7-day trial, extend to 14 days, and verify the change is reflected in the UI and session object.
  • Remove existing trial: Start with a 7-day trial, remove it, and verify the change is reflected in the UI and session object. Remove the trial using the same field that it was set with.
  • Error handling: Test invalid requests to ensure your error handling works correctly.
Was this page helpful?
YesNo