Accéder directement au contenu
Créez un compte
 ou
connecter-vous
Logo de la documentation Stripe
/
Créez un compte
Connectez-vous
AperçuMettre votre intégration à niveau
Paiements en ligne
PrésentationTrouver votre cas d'usageManaged Payments
Créer une page de paiement
Moyens de paiement
Interfaces de paiement
Scénarios de paiement
Paiements par TPE
Au-delà des paiements

Remarque

Cette page n'est pas encore disponible dans cette langue. Nous faisons tout notre possible pour proposer notre documentation dans davantage de langues et nous vous fournirons la version traduite dès qu'elle sera disponible.

Dynamically update trial durationsVersion bêta privée

Update trial durations in response to changes made during checkout.

Private preview

This feature 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).

Set up SDK
Server-side

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

Command Line
gem install stripe -v 15.1.0-beta.2

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

# 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 a new endpoint on your server to update the trial duration for a yearly upsell on the Checkout Session. You call this from the frontend in a later step.

Conseil en matière de sécurité

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

When designing the endpoint, we recommend the following:

  • Design endpoints for specific customer interactions instead of making them overly generic (for example, “extend trial for yearly upgrade” rather than a general “update” action). Specific endpoints help keep the purpose clear and make validation logic easier to write and maintain.
  • Avoid passing 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 Stripe’s API.

You can update trial durations using either:

  • trial_period_days: An integer that represents the number of days for the trial period, or empty string to remove the trial
  • trial_end: A Unix timestamp that represents when the trial should end, or 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. A trial set with trial_period_days can only be removed with trial_period_days: "", and a trial set with trial_end can only be removed with trial_end: "".
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 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'],
});

Invoke server updates
Client-side

Trigger the update from your front end by making a request to your server, and wrapping it in runServerUpdate. If the request is successful, the Session object updates 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.

Remarque

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.
Cette page vous a-t-elle été utile ?
OuiNon
Besoin d'aide ? Contactez le service Support.
Rejoignez notre programme d'accès anticipé.
Consultez notre log des modifications.
Des questions ? Contactez l'équipe commerciale.
LLM ? Lire llms.txt.
Propulsé par Markdoc