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.
var stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx', { betas: ['checkout_beta_4'] }); stripe.redirectToCheckout({...});
var stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx'); stripe.redirectToCheckout({...});
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 initems
had atype
andid
property. These are now combined intoprice
. See the Stripe.js reference for the current shape of theitems
parameter. successUrl
andcancelUrl
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.
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: ...
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.api_version = '2018-11-08; checkout_sessions_beta=v1' stripe.checkout.Session.create(...)
stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc' 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.apiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc"; Stripe.apiVersion = "2018-11-08; checkout_sessions_beta=v1"; Session.create(...);
Stripe.apiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc"; Session.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(...);
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.
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.
var stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx', { betas: ['checkout_beta_4'] }); stripe.redirectToCheckout({...});
var stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx'); stripe.redirectToCheckout({...});
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.