Checkout Beta Migration Guide

    Learn how to migrate from the beta of the new version of Checkout.

    If you are using the Checkout client integration, you can tell that you are using a beta version if you were passing betas: ['checkout_beta_4'] (or checkout_beta_3 or checkout_beta_2 ) when initializing Stripe.js.

    If you are using the Checkout server integration, you are using a beta version if you are passing checkout_sessions_beta=v1 as Stripe API version when initializing your Stripe API bindings.

    Your beta integration will continue to work, but we recommend that you make the changes outlined below as soon as you can.

    Integration Changes

    Remove the checkout_beta_4 (or checkout_beta_3 or checkout_beta_2) string when initializing Stripe.js.

    Before
    After
    var stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx', {
      betas: ['checkout_beta_4']
    });
    
    stripe.redirectToCheckout({...});
    var stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx');
    
    stripe.redirectToCheckout({...});
    Before
    After
    const stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx', {
      betas: ['checkout_beta_4']
    });
    
    stripe.redirectToCheckout({...});
    const stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx');
    
    stripe.redirectToCheckout({...});

    stripe.redirectToCheckout changes

    If you were on beta 2 or 3, you might have to change the shape of the configuration object you pass to redirectToCheckout.

    • In checkout_beta_2, each item in items had a type and id property. These are now combined into either sku or plan. See the Stripe.js reference for the current shape of the items parameter.
    • successUrl and cancelUrl are now required to be absolute URLs.

    You can also generate a new code snippet for your product in the Stripe Dashboard.

    Server-side code

    Remove the checkout_sessions_beta=v1 when setting the API version in your bindings.

    Before
    After
    curl https://api.stripe.com/v1/checkout/sessions \
      -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
      -H "Stripe-Version: 2018-11-08; checkout_sessions_beta=v1"
    ...
    
    curl https://api.stripe.com/v1/checkout/sessions \
      -u sk_test_4eC39HqLyjWDarjtT1zdp7dc:
    ...
    
    Before
    After
    Stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc'
    Stripe.api_version = '2018-11-08; checkout_sessions_beta=v1'
    Stripe::Checkout::Session.create(...)
    Stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc'
    Stripe::Checkout::Session.create(...)
    Before
    After
    stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc'
    stripe.api_version = '2018-11-08; checkout_sessions_beta=v1'
    stripe.checkout.Session.create(...)
    stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc'
    stripe.checkout.Session.create(...)
    Before
    After
    \Stripe\Stripe::setApiKey('sk_test_4eC39HqLyjWDarjtT1zdp7dc');
    \Stripe\Stripe::setApiVersion('2018-11-08; checkout_sessions_beta=v1');
    \\Stripe\\Checkout\\Session::create(...);
    \Stripe\Stripe::setApiKey('sk_test_4eC39HqLyjWDarjtT1zdp7dc');
    \\Stripe\\Checkout\\Session::create(...);
    Before
    After
    Stripe.apiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc";
    Stripe.apiVersion = "2018-11-08; checkout_sessions_beta=v1";
    Session.create(...);
    Stripe.apiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc";
    Session.create(...);
    Before
    After
    const stripe = require('stripe')('sk_test_4eC39HqLyjWDarjtT1zdp7dc');
    stripe.setApiVersion('2018-11-08; checkout_sessions_beta=v1');
    stripe.checkout.sessions.create(...);
    const stripe = require('stripe')('sk_test_4eC39HqLyjWDarjtT1zdp7dc');
    stripe.checkout.sessions.create(...);
    Before
    After
    The Go Client library did not support Checkout Sessions during the beta.
    The API version is statically defined in each version of the Go API library. Upgrade to the latest one to create Checkout Sessions.
    Before
    After
    The .NET Client library did not support Checkout Sessions during the beta.
    The API version is statically defined in each version of the .NET API library. Upgrade to the latest one to create Checkout Sessions.

    Client-side code

    Remove the checkout_beta_4 (or checkout_beta_3 or checkout_beta_2) string when initializing Stripe.js.

    Before
    After
    var stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx', {
      betas: ['checkout_beta_4']
    });
    
    stripe.redirectToCheckout({...});
    var stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx');
    
    stripe.redirectToCheckout({...});
    Before
    After
    const stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx', {
      betas: ['checkout_beta_4']
    });
    
    stripe.redirectToCheckout({...});
    const stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx');
    
    stripe.redirectToCheckout({...});

    Payment Methods instead of Sources

    The beta version of Checkout created a Source, whereas Checkout now creates a PaymentMethod. This change affects you if you were relying on the sources property of the Customers or on the source property of PaymentIntents.

    You can learn more in the Payment Methods API migration guide.

    Webhook Changes

    We will continue to send the checkout_beta.session_succeeded event, but we suggest you migrate to handling the checkout.session.completed event instead. The checkout.session.completed webhook includes the Checkout Sessions object.

    For more details about handling purchase fulfillment with Checkout, refer to the documentation.

    Subscription and Customer Changes

    Migrating off of the Checkout beta slightly changes the behavior of the Subscriptions that Checkout creates.

    The beta version of Checkout created a Source and set it as the default_source on the Customer it created. After the migration, Checkout will create a PaymentMethod and set it as the default_payment_method on the Subscriptions it creates.

    In the beta version of Checkout, successful Checkout Sessions for subscriptions had a value for both the payment_intent and subscription properties. After the migration, successful Checkout Session objects for subscriptions will only have a value for the subscription property, and the payment_intent property will be blank. If you still want to access the payment details for the first invoice, you can use session.subscription.latest_invoice.payment_intent.

    If you’re handling customer.subscription.created webhooks, be sure to verify that your handlers can accommodate subscriptions with initial statuses other than active and trialing prior to upgrading. The beta version of Checkout always creates subscriptions with these initial statuses, but the generally available version of Checkout can create subscriptions with an initial status of incomplete. See subscription states for more details.

    Was this page helpful? Yes No

    Send

    Thank you for helping improve Stripe's documentation. If you need help or have any questions, please consider contacting support.

    Questions?

    We're always happy to help with code or other questions you might have. Search our documentation, contact support, or connect with our sales team. You can also chat live with other developers in #stripe on freenode.

    On this page