Upgrade your online checkout

You can customize your online checkout to extend your brand, change messaging, serve up offers, and make other improvements to your customers' experience. To make sure that your customizations are compatible with ongoing changes made by Shopify, you need to update your checkout periodically.

To prepare for this upgrade, you need to do the following:

  1. Preview the new checkout and test your customer-facing checkout experience. Depending on the customizations that you've made to your checkout, you might need to make changes to your checkout.liquid file before you can upgrade.
  2. When you're satisfied with your changes, upgrade your store to use the new Shopify checkout.

Preview your checkout and test for errors

Before you upgrade your store to use the new version of the checkout, make sure that you preview the changes.

Pretend that you're a customer and create test checkouts. If you find any errors during these tests, then some of your checkout customizations are conflicting with other improvements in the new version. If that's the case, then you need to make changes to your checkout.liquid file before you upgrade.

Resolving errors


  1. From the Shopify admin, go to Online Store > Themes.
  2. Click Actions and then click Duplicate.
  3. From More themes, find your duplicated theme, and then click Actions > Edit code. Make your edits and test them using this duplicate and unpublished version of your theme.
  1. Open the checkout.liquid file.

  2. Preview the checkout.liquid file from your duplicated theme using the new Shopify checkout:

    1. Go to your Shopify admin's Checkout upgrade page, click Preview checkout, and then choose the duplicated theme.
    2. Complete test orders in the preview.

If you have errors or notice issues in how the checkout looks visually, then you need to edit your checkout.liquid file to address them.

Upgrade to the new Shopify checkout

Upgrading your checkout is a two-step process that requires you to upgrade the Shopify checkout and replace the current, published theme with the duplicate copy that contains your changes.

Choose a slower time of day to upgrade (such as early morning, late evening, or on the weekend) to minimize any potential disruptions.


  1. From the Checkout upgrade page, click Upgrade checkout (this button is located at the bottom of the page).

  2. If you encountered errors when first previewing your theme, then first ensure that they've been resolved (refer to Resolving errors above). Then, publish your updated duplicate theme:

    1. From your Online Store, click Themes.
    2. Find your duplicate theme and click Action > Publish.

Your checkout is upgraded and your duplicate theme is now your current theme.

What's new in Shopify checkout

The new version of Shopify checkout contains the following changes and new features:

Discount liquid variables

Several new liquid variables related to the display of discounts have been introduced throughout the checkout process. These changes help to represent automatic and script-based discounts in a way that makes sense to your customers.

Table listing new liquid variables
Variable Definition
checkout.cart_level_discount_applications Returns an array of any cart-specific discount applications for the checkout.
line_item.discount_allocations Returns a list of all discount allocations containing the discounted amount and the reference to the parent discount application. line_item.discount_allocations is available on line items in carts, checkouts, orders, and draft orders.
line_item.final_line_price Returns the combined price of all the items in the line item. This is equal to line_item.final_price multiplied by line_item.quantity.
line_item.final_price Returns the price of the line item including all line level discount amounts.
line_item.line_level_discount_allocations Returns a list of line-specific discount allocations containing the discounted amount and the reference to the parent discount application. line_item.line_level_discount_allocations is available on line items in carts, checkouts, orders, and draft orders.
line_item.total_discount Returns the total amount of all discounts applied to the line item. This attribute only has a value if you're using the Script Editor app.

Shop opt in

A dedicated phone number field has been added to the order status page. Customers are prompted to enter a mobile number to receive shipping updates by text. These texts also include a link to the Shop app.

Order editing

When order editing is made available for Shopify Plus merchants, it will allow for capturing additional outstanding payments on edited orders using the Shopify checkout. There are some changes to the checkout page to ensure that it works as intended:

  • The customer can't change their contact information, shipping address, or shipping method.
  • Additional line items indicating the order total and the amount already paid for.
  • The Complete purchase button changes to Pay now. Total changes to Amount to pay.
  • Instead of the breadcrumb information showing where the customer is in the checkout process, the customer will see a collapsible banner detailing additional information about the order:
    • The additional payment amount.
    • Products added or removed from the order.
    • The order number.

Image showing the checkout page when additional payments are needed

These changes will take effect only when an order is edited and requires an additional payment from your customer.

If your checkout customizations use the breadcrumb to identify the current step of the checkout, then you should use the Shopify.Checkout.step object instead. Refer to Step identification to learn more.

Accessibility improvements

Several changes have been introduced to the checkout to ensures compliance with web accessibility standards. This makes it easier to navigate the checkout process for customers using accessibility technology, such as screen readers.

  • Breadcrumbs are now wrapped in a nav element in all checkout steps. The aria-current attribute has been moved to the li element from the span element.
  • Order summaries now reside in an aside element.
  • The discount code field ID for mobile customers has been changed from checkout_reduction_code to checkout_reduction_code_mobile in all checkout steps.
  • Accessibility attributes have been added to the map for the Thank You and Order Status pages. The map now has role=region and aria-label with the shipping address.
  • step and step__section wrapper divs have been added to the Order Status, Out of Stock, and Thank You pages.
  • Semantic HTML5 elements have been introduced to the checkout process and role attributes have been updated.
    • The order summary is now inside an aside element.
    • The div for .main__header is now a header element with role=banner.
    • The div for .main__content is now a main element with role=main.
    • The div for .main__footer is now a footer element with role=contentinfo.
    • The div for banner is now a header with role=banner.

Padding removed

The Order Status, Out of Stock, and Thank You pages have had white space removed between the shop name and order number. This extra padding was removed from the div.section.section--page-title section.

Payment method display

The total amount of an order now appears to customers on the order status page in the Payment method section.

Placeholder strings removed

The Email placeholder and Email or phone placeholder fields have been removed from the language options in your theme settings. Any necessary changes can be made in the Email label and Email or phone label fields, respectively. To access these fields, go to Online Store > Themes and then click Actions > Edit languages > Checkout and system.

Saved customer address display

The way that saved addresses are displayed during the checkout for logged-in customers has changed.

Address options are displayed in the following order:

  1. The default saved address.
  2. The most recently added addresses, from most to least recent.
  3. The option to use a new address.

The drop-down menu displays a maximum of five addresses.

3D Secure authentication

3D Secure technology provides an additional layer of security that customers need to complete before they can finish making their purchase, and powers services such as Verified by Visa, Mastercard Identity Check, or Amex SafeKey. During checkout, some customers might be redirected to their bank's portal for additional authentication. To learn more, refer to Understanding PSD2 and Strong Customer Authentication.

Merchants located in the European Economic Area (EEA) and United Kingdom can use Cardinal to offer 3D Secure checkouts. Refer to 3D Secure with Cardinal to learn more.

The decision of which checkouts require additional verification is determined by the bank, and can't be controlled through the Shopify admin. No action is required to enable this change.

Additional Google Analytics JavaScript field changes

JavaScript entered into the Additional Google Analytics JavaScript section in your Shopify admin at Online Store > Preferences is added to the checkout as a non-visible iFrame. This doesn't affect the JavaScript used for analytics purposes, but does prevent other changes from being made to the checkout. If you want to add custom JavaScript to your checkout for other reasons, then add it to the checkout.liquid file directly.

CSS changes

heading-* and text-container CSS classes have been added to all checkout steps.

Error messaging

An error banner has been added that informs customers when their chosen express checkout payment method isn't available. This banner appears at the top of the Contact Information step of the checkout.

The error banner informing customers that a previous shipping rate is no longer valid has been moved. This banner now appears directly above the available shipping options.

Ready to start selling with Shopify?

Try it free