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 client and 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', {
  betas: ['checkout_beta_4']
});

stripe.redirectToCheckout({...});

var stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx');

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', {
  betas: ['checkout_beta_4']
});

stripe.redirectToCheckout({...});

const stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx');

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 price. 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: \
  -H "Stripe-Version: 2018-11-08; checkout_sessions_beta=v1"
...

curl https://api.stripe.com/v1/checkout/sessions \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc:
...
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.api_version = '2018-11-08; checkout_sessions_beta=v1'
Stripe::Checkout::Session.create(...)

Stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc'
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.api_version = '2018-11-08; checkout_sessions_beta=v1'
stripe.checkout.Session.create(...)

stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc'
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\Stripe::setApiVersion('2018-11-08; checkout_sessions_beta=v1');
\\Stripe\\Checkout\\Session::create(...);

\Stripe\Stripe::setApiKey('sk_test_4eC39HqLyjWDarjtT1zdp7dc');
\\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";
Stripe.apiVersion = "2018-11-08; checkout_sessions_beta=v1";
Session.create(...);

Stripe.apiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc";
Session.create(...);
Stripe.apiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc";
Session.create(...);

Before

After

const stripe = require('stripe')('sk_test_4eC39HqLyjWDarjtT1zdp7dc', {
  apiVersion: '2018-11-08; checkout_sessions_beta=v1',
});
stripe.checkout.sessions.create(...);
const stripe = require('stripe')('sk_test_4eC39HqLyjWDarjtT1zdp7dc', {
  apiVersion: '2018-11-08; checkout_sessions_beta=v1',
});
stripe.checkout.sessions.create(...);

const stripe = require('stripe')('sk_test_4eC39HqLyjWDarjtT1zdp7dc');
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', {
  betas: ['checkout_beta_4']
});

stripe.redirectToCheckout({...});

var stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx');

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', {
  betas: ['checkout_beta_4']
});

stripe.redirectToCheckout({...});

const stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx');

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.

Integration Changes

stripe.redirectToCheckout changes

Server-side code

Client-side code

Payment Methods instead of Sources

Webhook Changes

Subscription and Customer Changes

`stripe.redirectToCheckout` changes