Dynamically update trial durationsPrivate preview

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:

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.

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.

Security tip

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

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:

Create a subscription Checkout Session with an initial trial period.
Trigger your server endpoint by interacting with the UI element you created.
Verify the trial duration is updated correctly in the Checkout Session.
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.