Skip to content
Create account
 or
Sign in
The Stripe Docs logo
/
Create account
Sign in
OverviewUpgrade your integration
Online payments
OverviewFind your use case
Payment methods
Payment interfaces
Payment scenarios
In-person payments
Other Stripe products

Elements with Checkout Sessions API beta changelog

Keep track of changes to the Elements with Checkout Sessions API beta integration.

Copy page

Warning

This doc contains changelogs related to beta versions of Elements with Checkout Sessions API.

If you’re already on the Basil release of Elements with Checkout Sessions API, this doc does not apply to you.

Migrating to Basil

Changes

  • Breaking Asynchronous methods, such as confirm or applyPromotionCode, resolve with a different schema:
    • If successful, the updated session state is populated under the session key. Previously, this was under the success key.
  • Breaking An error is now thrown when passing in returnUrl on confirm when return_url has been already set on the Checkout Session.
  • Breaking The return URL redirected to after a successful confirmation previously had inconsistent query parameters. Extra parameters are now removed and the URL only contains what’s provided in returnUrl on confirm or return_url on the Checkout Session.
  • Breaking Improves latency on Checkout Session API for subscription-mode Sessions and fixes a bug that prevented your customers from updating a Session after the first payment attempt
    • The change creates the subscription after the user has completed the payment, so payment_intent.invoice is null until the Checkout Session completes.
    • We recommend using the checkout_session.completed webhook if you’re currently relying on payment_intent.invoice, which ensures payment_intent.invoice is present.
    • To learn more, read the API changelog.
  • Added percentOff to discountAmounts as an option to display discounts.

Upgrade

Before migrating to Basil, first update your integration to custom_checkout_beta_6.

  • If you’re using any Stripe NPM packages, you must first upgrade @stripe/stripe-js to at least 7.0.0 and @stripe/react-stripe-js to at least 3.6.0.
  • If you’re loading Stripe.js through the script tag, update the script tag to use versioned Stripe.js by replacing the tag as follows:
checkout.html
<head>
 <title>Checkout</title>
 <script src="https://js.stripe.com/v3"></script>
 <script src="https://js.stripe.com/basil/stripe.js"></script>
</head>
  • Remove the Stripe.js beta header when initializing Stripe.js.
checkout.js
const stripe = Stripe(
  
'pk_test_TYooMQauvdEDq54NiTphI7jx'
, {
  betas: ['custom_checkout_beta_6'],
  }
);
  • Remove the API version beta header and specify the API version to be at least 2025-03-31.basil on your back-end integration.
Before
After
// Set your secret key. Remember to switch to your live secret key in production.
// See your keys here: https://dashboard.stripe.com/apikeys
import Stripe from 'stripe';
const stripe = new Stripe(
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'
, {
  apiVersion: '2025-03-31.basil; custom_checkout_beta=v1' as any,
});
// Set your secret key. Remember to switch to your live secret key in production.
// See your keys here: https://dashboard.stripe.com/apikeys
import Stripe from 'stripe';
const stripe = new Stripe(
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'
, {
  apiVersion: '2025-03-31.basil' as any,
});

Beta changelog

Elements with Checkout Sessions API beta uses two kinds of beta versions:

  • A Stripe.js beta header (e.g., custom_checkout_beta_6), which is set on your front-end integration.
  • An API version beta header (e.g., custom_checkout_beta=v1), which is set on your back-end integration.

Front-end beta versions

Specify the front-end beta version when initializing Stripe.js.

custom_checkout_beta_6

If you’re using any Stripe NPM packages, you must first upgrade @stripe/stripe-js to at least 6.1.0 and @stripe/react-stripe-js to at least 3.5.0.

  • Breaking The sign of total.appliedBalance has been flipped. A positive number now increases the amount to be paid, and a negative number decreases the amount to be paid.
  • Breaking Replaced clientSecret with fetchClientSecret. Update your integration to pass an async function resolving to the client secret instead of passing a static value.
  • Breaking Elements methods has been renamed.
    • If you’re using React Stripe.js, you don’t need to do anything except upgrade @stripe/react-stripe-js.
    • If you’re using HTML/JS:
      • Use createPaymentElement() instead of createElement('payment').
      • Use createBillingAddressElement() instead of createElement('address', {mode: 'billing'}).
      • Use createShippingAddressElement() instead of createElement('address', {mode: 'shipping'}).
      • Use createExpressCheckoutElement() instead of createElement('expressCheckout').
      • Use getPaymentElement() instead of getElement('payment').
      • Use getBillingAddressElement() instead of getElement('address', {mode: 'billing'}).
      • Use getShippingAddressElement() instead of getElement('address', {mode: 'shipping'}).
      • Use getExpressCheckoutElement() instead of getElement('expressCheckout').
  • Breaking Updated fields related to confirmation to more accurately reflect session state.
    • canConfirm now responds to any mounted Billing Address Element or Shipping Address Element.
    • canConfirm now becomes false if there is an in-flight confirmation.
    • Removed confirmationRequirements.
  • Breaking updateEmail now throws an error if customer_email was provided when creating the Checkout Session. If you intend to prefill an email that your customer can update, call updateEmail as soon as the page loads instead of passing customer_email.
  • Breaking returnUrl must be an absolute URL (for example, starts with https:// rather than a relative URL, like /success).
  • Breaking Updated pricing fields to a nested object for ease of rendering.
    • Replaced numeric values with an object containing amount (a formatted currency string, such as $10.00) and minorUnitsAmount, an integer representing the value in the currency’s smallest unit. If you’re already reading the amount, read instead from minorUnitsAmount.
    • You must either read total.total.amount or each of total.total.minorUnitsAmount and currency and minorUnitsAmountDivisor from the checkout object and display in your UI, otherwise an error will be thrown. This helps keep your checkout page in sync as the CheckoutSession updates, including adding future Stripe features, with minimal UI code changes.
  • Customer tax IDs can now be collected. Learn how to collect tax IDs.
  • A test mode-only assistant is now available at the bottom of your checkout page, offering guidance for your integration and shortcuts for common test scenarios.

custom_checkout_beta_5

  • Breaking The initCustomCheckout function has been renamed to initCheckout
    • Within React Stripe.js, CustomCheckoutProvider has been renamed to CheckoutProvider and useCustomCheckout has been renamed to useCheckout.
  • Breaking To confirm the Express Checkout Element, call confirm, passing the confirm event as expressCheckoutConfirmEvent
    • Previously, Express Checkout Element was confirmed by calling event.confirm().
  • Breaking When confirm is called, Payment Element and Address Element will validate form inputs and render any errors.
  • Breaking Error messages have been standardized and improved.
    • Errors returned/resolved by a function represent known scenarios like invalid payment details or insufficient funds. These are predictable issues that can be communicated to your customer by displaying the message on the checkout page.
    • Errors thrown/rejected by a function represent errors in the integration itself, such as invalid parameters or configuration. These errors are not meant to be displayed to your customers.
  • Breaking Asynchronous methods, such as confirm or applyPromotionCode, resolve with a different schema:
    • A type="success"|"error" discriminator field has been added.
    • If successful, the updated session state is populated under the success key. Previously, this was under the session key.
    • Otherwise, the error continues to be populated under the error key.
  • Added the email, phoneNumber, billingAddress, and shippingAddress options to confirm.
  • Breaking Address Element no longer automatically updates the billingAddress or shippingAddress fields on the Session.
    • So long as Address Element is mounted, form values will automatically be used when calling confirm.
    • Listen to the change event to use the Address Element value before confirmation.

custom_checkout_beta_4

  • Added images to the Session object.
  • Added fields as an option when creating the Payment Element.
  • Added paymentMethods as an option when creating the Express Checkout Element.
  • Breaking Passing invalid options to createElement now throws an error. Previously, unrecognized options would be silently ignored.
  • Breaking updateEmail and updatePhoneNumber apply changes asynchronously. Calling these methods before the customer finishes entering complete values might cause poor performance.
    • Instead of calling updateEmail or updatePhoneNumber on each input’s change event, wait until your customer finishes the input, such as on input blur or when they submit the form for payment.
    • updateEmail now validates that the input is a properly formed email address and returns an error if an invalid input is used.
    • updatePhoneNumber still performs no validation on the input string.

custom_checkout_beta_3

  • The following fields have been added to the Session object:
  • Saved cards can now be reused. Learn how to save and reuse payment methods.
  • Breaking The default layout of the Payment Element has been changed to accordion.
    • To continue using the previous default layout, you must explicitly specify layout='tabs'.
  • Breaking The default behavior of confirm has been changed to always redirect to your return_url after a successful confirmation.
    • Previously, confirm redirected only if the customer chooses a redirect-based payment method. To continue using the old behavior, you must pass redirect=‘if_required’ to confirm.

custom_checkout_beta_2

custom_checkout_beta_1

This is the initial front-end beta version.

Back-end changelog

Specify the back-end beta version when setting up your server library.

There are no changes to the back-end beta version.

Was this page helpful?
YesNo
Need help? Contact Support.
Join our early access program.
Check out our changelog.
Questions? Contact Sales.
LLM? Read llms.txt.
Powered by Markdoc