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.

Do the following to prepare for this upgrade:

  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.


  1. From your Shopify admin, go to the Checkout upgrade page, and then click Preview checkout.
  2. Select your current theme from the list, and then click Preview.
  3. Create a test checkout by proceeding through the checkout process as a customer.

If you find any errors during these tests, then some of your checkout customizations might conflict with 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 your Shopify admin, go to Online Store > Themes.
  2. Click the ... button, and then click Duplicate.
  3. From More themes, find your duplicated theme, and then click the ... button > Edit code. Make your edits and test them using this duplicate and unpublished version of your theme.
  4. Open the checkout.liquid file.
  5. Preview the checkout.liquid file from your duplicated theme using the new Shopify checkout:
    1. From your Shopify admin, go to the 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 the ... button > 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:


Multiple sections have been added to the Shopify Checkout so that you can offer subscription products while maintaining your checkout customizations. These sections will let you sell subscription products and process recurring payments directly within Shopify Checkout.

After completing the checkout upgrade, you can offer subscriptions by adding a subscription app from the Shopify App Store, or build a custom app with new subscription APIs.

Learn more about subscriptions in the Shopify Help Center:

  • When subscriptions are activated, shipping methods used for subscriptions are displayed separately from those of one-time purchases.
  • .product_description_variant Span.product_description_selling_plan displays as an additional line item property when there's a subscription associated with the product.
  • A recurring total with an accompanying tooltip displays below the total in the order summary.
  • Subscription shipping options are displayed when a subscription product is included in the order.


New post-purchase upsell apps are available in the Shopify App Store. These apps present post-purchase offers to your customers directly inside Shopify Checkout, and modify their completed order to include the upsold product without re-entering any billing or shipping information.

This checkout upgrade includes changes to your checkout files that allow post-purchase upsells to work with your customized checkout.

Learn more about post-purchase upselling.

When a valid post-purchase app is installed in the Shopify admin, customers will receive post-purchase offers.

Tipping at checkout

Tipping options can be used to let customers include a tip with their online order, or to collect donations instead of tips. When tipping is activated, an Add tip section displays on the payment method step of checkout. The Add tip section includes three pre-selected tip options in addition to a field to enter a custom tip amount.

When tipping is activated, an Add tip section displays on the payment method step of checkout.

Learn more about offering tipping options.

Pickup in store and local delivery

Pickup in store and delivery are new delivery methods that let customers receive their orders locally. When these delivery methods are activated, customers can select Pickup in store or delivery on the shipping step of checkout.

Learn how to activate pickup in store and local delivery.

  • Additional fields for local delivery display when local delivery is activated and selected by the customer.
  • If pickup in store is activated, then a delivery method section is displayed to the customer on the Information page in the checkout. If shipping isn't available, then only pickup information is displayed.
  • Delivery methods are displayed as distinct tabs.
    • Selecting Ship prompts customers to enter their shipping information, and displays available shipping methods when Continue to shipping is clicked.
    • Selecting Pick up displays a list of pickup locations. Customers click the radio button for the desired pickup location and then click Continue to payment.
  • If customers select Pick up in the shipping step of the checkout, then shipping information isn't collected. Customers are required to enter billing information in the payment step of the checkout.
  • Local delivery instructions display on the order status page. These can be edited by going in your Shopify admin to Settings > Shipping and delivery. In the Pickup in store section, find the location you want to edit and click Manage.
  • The order status page has been updated to display the progress of deliveries and pickups. Messages are displayed when:
    • an order has been prepared and is ready for delivery.
    • a delivery has been completed. This message also provides a link to re-order the same items.
    • a pickup order has been confirmed, indicating that the customer will receive an email when it's ready to be picked up.
    • a pickup order is ready to be picked up.
    • a pickup order has been picked up.

Additional international fields

Some countries have unique shipping regulations you need to meet for your shipments to reach your customers. Additional fields are now available for countries with unique shipping regulations. These new fields display on the payment method step of the checkout.

Learn more about additional international fields.

  • Additional checkout fields appear only to customers in Brazil, South Korea, Italy, and China.

Track order with Shop button

The Track order with Shop button on the order status and thank you pages has been updated with a new design.

Learn more about the Shop app.

  • A text button has been added that prompts customers to track their purchase on the Shop app.
  • Parameters have been added to display Shop Pay tracking.
  • Rendering for the Track order with Shop button for the following cases:
    • attempted delivery
    • confirmation
    • delivered
    • failed
    • in transit
    • non-shippable
    • out for delivery

Order status page updates

Several updates have been made to the order status page.

  • A dedicated section for gift card information has been created that displays when a gift card has been purchased.
  • Subscriptions information has been added.
  • The class icon-svg--align-text-bottom has been removed.
  • data-step="thank-you" has been changed to data-step="thank_you". If you use this attribute to identify which page of the checkout the customer is on, then use the Shopify.Checkout.page JavaScript object instead.
  • An order status card has been added.

General file changes

  • div.content-box__row now has role="table".
  • If the customer is on the thank you step and has the QR bundle, show_qr.js is added.
  • A check has been added to make sure the customer has access to the checkout.
  • Gift cards are now displayed with checkouts/order_status/gift_cards.
  • Contact information direction has been fixed with enforce_content_directionality.
  • Shipping information has been moved to checkouts/web/checkouts/contact_information/pickup.
  • The display of multiple shipping lines in the order summary sidebar is now supported.
  • tr.total-line will only be displayed if there are updated totals.
  • Generic payment lines are now supported.
  • Changing currency during checkout is now supported.
  • #payment-gateway-subfields now has classes:
    • .radio-wrapper content-box__row .content-box__row--secondary
    • .card-fields-container
  • Credit card tooltip has been adjusted and is now in div.field__icon.
  • The Aria label has been removed from the shipping rates full description.
  • Shipping rates form fields have been moved to checkouts/web/checkouts/shipping_method/shipping_rate_additional_fields.

Skeletons/loading states

The loading states for checkout pages have been updated, adding skeletons that are visible while the page loads, or selectively hiding some elements until loading is complete. These changes optimize load times.

  • Objects hidden while loading:
    • del.total-recap__original-price
    • .total-line__price span.payment-due__currency
    • span.order-summary__emphasis
  • Objects that show a skeleton while loading:
    • Span.total-recap__final-price
    • .product__price del.order-summary__small-text
    • .product__price del.order-summary__emphasis
    • .total-line__price span.payment-due__price
    • .total-line__price span.order-summary__emphasis
    • .total-line__price span.visually-hidden
    • .total-line__price.total-line--subtotal span.order-summary__emphasis

Error messaging

New error messaging has been added to the checkout:

  • A civic number warning has been added to the address field.
  • A warning indicating that there are no shipping rates available for a cart, destination, or country has been separated into two distinct warning messages: one warning message indicating that there are no rates available for a cart or destination, and a separate warning indicating that there are no rates available for a country.
  • A warning banner has been added to the checkout when completing a purchase is attempted in a development store.
  • A notice has been added that displays when the customer won't be charged during checkout.
  • A warning banner has been added to indicate an authentication change error.
  • An error message has been added to indicate when shipping methods are unavailable at the shipping step of the checkout.

Data attribute changes

Trekkie has been removed from the following objects:

  • Continue_shipping_button
  • Get_shipping_updates_button
  • Shipping_updates_handle_field
  • Shipping_updates_submit_button
  • Change_shipping_address_link
  • breadcrumb_cart_link
  • apply_discount_button
  • Have_an_account_login_link
  • Email_or_phone_field
  • Email_field
  • buyer_accepts_marketing_field
  • Change_billing_address_link
  • Change_contact_method_link
  • Change_payment_method_link
  • Change_pickup_method_link
  • Change_shipping_address_link
  • Checkout input fields:
    • {type}_address_field
    • {type}_firstname_field
    • {type}_lastname_field
    • {type}_company_field
    • {type}_address1_google_autocomplete_field
    • {type}_address1_field
    • {type}_address2_field
    • {type}_city_field
    • {type}_country_field
    • {type}_province_field
    • {type}_zip_google_autocomplete_field
    • {type}_phone_field

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.

  • Added role="list" on ul for the following:
    • u.breadcrumb
    • ul.payment-method-list
    • ul.os-timeline
    • ul.policy-list
  • The tool-tip has been removed from aria-labelledby on telephone_field.
  • In Shop, the input label has been changed to refer to the phone.
  • Added h3 headings when waiting for taxes.
  • Added h3 headings when redirecting.
  • When loading shipping methods, the p tag has been changed to an h3 tag.
  • Autocomplete now refers to mobile tel instead of phone.
  • Updated div[data-processing-order] by adding role="region".
  • Updated div[data-announce-change] with the following:
    • added role="region"
    • set aria-labelledby to match the id of the header element
    • set aria-describedby to match the id of the content container element
  • Updated div.content-box blank-slate with the following:
    • added role="region"
    • set aria-labelledby to match the id of the header element
  • Express Checkout grid has been improved to use ul and li elements instead of div.
  • Updated the order summary with the following:
    • improved clarity on sale price and regular price
    • changed span to dl tag
    • changed del tag to dt and dd tags.
  • Updated payment detail methods with the following:
    • span.radio__label__accessory changed to div.radio__label__accessory
    • span.visually-hidden changed to h3.visually-hidden
    • span.payment-icon-list__more changed to li.payment-icon-list__more
    • span.content-box__small-text changed to small.content-box__small-text
Can't find answers you're looking for? We're here to help you.