Skip to main content

checkout.liquid

Deprecated

checkout.liquid is now unsupported for the Information, Shipping, and Payment checkout steps. checkout.liquid, additional scripts, and script tags are deprecated for the Thank you and Order status pages and will be sunset on August 28, 2025.

Stores that currently use checkout.liquid for the Thank you and Order status pages need to upgrade to Shopify Extensions in Checkout before the deadline.

Shopify Scripts will continue to work alongside Shopify Extensions in Checkout until June 30, 2026.

Learn how to build checkout extensions that extend the functionality of Shopify checkout.

The checkout.liquid layout renders the checkout and is available only to Shopify Plus merchants. If your store isn't on Shopify Plus, then you can customize your checkout pages in the theme editor.


The checkout.liquid layout is located in the layout directory of the theme:

└── theme
├── layout
| ├── theme.liquid
| └── checkout.liquid
├── templates
...

The checkout.liquid layout has the following format by default:

checkout.liquid

<!DOCTYPE html>
<html lang="{{ locale }}" dir="{{ direction }}" className="{{ checkout_html_classes }}">
<head>
<meta charset="utf-8" />
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
<meta name="viewport" content="width=device-width, initial-scale=1.0, height=device-height, minimum-scale=1.0, user-scalable=0" />
<meta name="referrer" content="origin" />

<title>{{ page_title }}</title>

{{ content_for_header }}

{{ checkout_stylesheets }}
{{ checkout_scripts }}
</head>
<body>
{{ skip_to_content_link }}

<header className="banner" data-header role="banner">
<div className="wrap">
{{ content_for_logo }}
</div>
</header>

{{ order_summary_toggle }}
<div className="content" data-content>
<div className="wrap">
<div className="main">
<header className="main__header" role="banner">
{{ content_for_logo }}
{{ breadcrumb }}
{{ alternative_payment_methods }}
</header>
<main className="main__content" role="main">
{{ content_for_layout }}
</main>
<footer className="main__footer" role="contentinfo">
{{ content_for_footer }}
</footer>
</div>
<aside className="sidebar" role="complementary">
<div className="sidebar__header">
{{ content_for_logo }}
</div>
<div className="sidebar__content">
{{ content_for_order_summary }}
</div>
</aside>
</div>
</div>

{{ tracking_code }}
</body>
</html>

The checkout.liquid layout has specific checkout objects to render various checkout content, depending on the checkout step.

The checkout has the following steps:

StepDescription
Inventory issuesThis step is displayed if one or more of the cart items is out of stock, or the inventory level is below what the customer has requested. Customers are shown a confirmation button that will update their cart with the available item quantities.
Contact informationThe customer enters their email address and will have the option to log in if customer accounts are enabled for the store. If any cart items require shipping, then the customer is shown a shipping address form. Otherwise, the customer is shown a billing address form.
Shipping methodThe customer selects a shipping option or edits their shipping information. This step is skipped when none of the cart items require shipping. Skipping the shipping method is common for merchants selling digital products or services. Clicking Edit shipping information returns the visitor to the Customer information step.
Payment methodThe customer chooses a payment method and, if applicable, enters payment information. Some payment providers require the customer to complete payment information on a different site. Customers can also specify a different billing address during this step.
Review order

Optional based on checkout settings. The customer confirms their order total, shipping and billing addresses, and payment details by clicking Complete order.

This step might be required if the store is operating in the European Union.

Processing/forwardingA temporary page shown to customers as their order is being processed, or as they are being redirected to an off-site payment provider. The message displayed during this step depends on your checkout's translation settings.
Order statusThe last step of checkout. This step is displayed after an order is complete. Learn more ›

On every step, an Order summary showing the products, price, taxes, and shipping costs is displayed in the right column. This column collapses at mobile breakpoints.

Tip

You can use JavaScript to identify the current step.

ObjectDescriptionRequired
content_for_headerThe scripts from Shopify for features like hCaptcha, Shopify apps, and more. You need to add a reference to this object between the <head> and </head> HTML tags.Yes
content_for_layoutThe form fields and content for each step of the checkout process. You need to add a reference to this object between the <body> and </body> HTML tags.Yes
localeThe currently-selected locale.No
directionThe CSS direction of the content. For example, ltr or rtl.No
page_titleThe page title. Commonly wrapped in <title> and </title> tags.No
skip_to_content_linkA hidden link for accessibility that allows users to skip to the main content.No
checkout_html_classesA string that should be added to the <html> tag to benefit from Shopify's default CSS.No
checkout_stylesheetsShopify's checkout stylesheets. It's recommended that you don't remove this, even if you have your own stylesheets, as it requires extensive work to replace the default styling.No
checkout_scriptsShopify's JavaScript files.No
content_for_logoThe store logo, as determined by the checkout settings.No
breadcrumbThe list of steps required to complete the checkout. The breadcrumb doesn't display on the final review step during checkout.No
order_summary_toggleThe markup necessary to show and hide the order summary on mobile devices.No
content_for_order_summaryThe content summary, including line items, discounts, taxes, and totals.No
alternative_payment_methodsThe list of available express payment methods, such as PayPal.No
content_for_footerThe list of your store policies or, if the list is empty, a copyright notice.No
tracking_codeThe JavaScript responsible for Google Analytics and Facebook Pixel tracking.No
checkoutThe checkout object.No
Caution

If you don't include the required objects in your checkout.liquid template, then you can't save or update the file using the code editor or tools like Shopify CLI.


When working with checkout.liquid, you should familiarize yourself with the following concepts:

Anchor to Access checkout.liquidAccess checkout.liquid

To enable or disable access to checkout.liquid, Shopify Plus merchants must contact support.

Before requesting access to checkout.liquid, you should be familiar with the following versions of checkout and their implications:

VersionDescription
StandardThe default checkout. It's used if access to checkout.liquid isn't enabled, and is automatically updated as Shopify releases updates and features for the checkout.
Maintenance

Used when access to checkout.liquid is enabled. It's a stable version of Standard, frozen at a specific time. This means that it's not automatically updated. If you use Maintenance, then you can get access to updates and features in the following ways:

Anchor to Add checkout.liquid to your themeAdd checkout.liquid to your theme

If access to checkout.liquid has been enabled, then you can follow the steps below to add the layout to your theme through the code editor in the Shopify admin:

  1. From your Shopify admin, go to Online Store > Themes.

  2. Find the theme that you want to edit, and then click ... > Edit code.

  1. In the Layout directory, click Add a new layout.
  2. In the drop-down list, select checkout, and then click Create layout.

You should now see checkout.liquid listed in the Layout directory.

Anchor to Customize checkout contentCustomize checkout content

You can't edit the content generated by any of the checkout objects, required or optional, before they're rendered. The only exceptions to this are for translation settings, theme editor settings, and some options made available in the Shopify admin.

If you need to customize the content output by a checkout object, then you need to use JavaScript to alter the content after it's been rendered. To learn more about customizing this content, refer to Best practices for editing checkout.liquid.

The checkout is all hosted on one page, which means that the URL remains the same regardless of which step of the process a customer is on. To account for this, you can use the following JavaScript objects to identify where the customer is in the checkout process.

Tip

The above JavaScript objects can be viewed using your browser's developer tools.

Anchor to Shopify.Checkout.stepShopify.Checkout.step

An object that shows which step of the checkout the customer is on. It returns one of the following results:

  • contact_information
  • shipping_method
  • payment_method
  • processing - This is the step between the payment_method step and the thank_you page.
  • review - This is an optional step set in the Shopify Admin.
Note

This object is defined only when the customer first visits the Order Status page.

Anchor to Shopify.Checkout.pageShopify.Checkout.page

An object that shows which type of page the customer is on. It returns one of the following results:

  • show - A page template for various steps of the checkout process.
  • stock_problems - A page that displays if there's an inventory issue with any cart items.
  • processing - A page that displays while the payment is being processed.
  • forward - A page from PayPal or another third-party gateway.
  • thank_you
Note

This object is defined only when the customer first visits the Order Status page.

Anchor to Shopify.Checkout.OrderStatusShopify.Checkout.OrderStatus

An object that can be used for adding content to the Order status page. It can also help determine whether the customer is on a Thank You page or an Order Status page.

The Order Status page is usually considered as a checkout page. However, the first time a customer visits the page, it's considered as a Thank You page, where the Shopify.Checkout.step and Shopify.Checkout.page objects are defined.

If the customer revisits or reloads the page, then this checkout is converted to an order, and the page loads as an Order Status page, where the Shopify.Checkout.step and Shopify.Checkout.page objects are undefined and the Shopify.Checkout.OrderStatus object is defined.

All of the checkout steps are hosted at a single URL path, where the content is loaded dynamically depending on the current step. There are two main page events that are triggered during this process:

The page:load event is triggered when the content of each step is loaded. This is the default event that you should use when adding content into the page on load.

Example

$(document).on('page:load', function() {
// Add content
});

The page:change event is triggered when the customer is on the same checkout step, but part of the content has changed. For example, this event triggers when the discount form is submitted.

If you add content to the Document Object Model (DOM) with only page:load, then there’s a risk that it could be overwritten by a page:change event. To avoid this issue, you should watch for both events when adding content.

Example

$(document).on("page:load page:change", function() {
// Add content
});

The checkout contains its own version of jQuery, which can be accessed using Checkout.$.

Example

(function($) {
$(document).on("page:load page:change", function() {
// Add your customizations
});
})(Checkout.$);
Note

The checkout's version of jQuery is not always the most recent version. If you need any functionality from a more recent version of jQuery, then you'll need to include it specifically.

Anchor to Capture checkout attributesCapture checkout attributes

You can capture checkout attributes in a similar way to capturing cart attributes.

To capture a checkout attribute, include an input with an attribute of name="checkout[attributes][attribute-name]", where attribute-name is the desired name of your attribute, inside the main checkout form.

Example

<input type="text" name="checkout[attributes][custom attribute]" />
Tip

If you're collecting attributes on the Payment method step, then you should populate them with a placeholder value before allowing the order to proceed. If the attribute has a blank value, then it can cause an error noting that the checkout has changed.

Note that capturing checkout attributes will remove any existing cart attributes. To learn how to avoid this issue, refer to Preserve cart attributes below.

Anchor to Preserve cart attributesPreserve cart attributes

When capturing checkout attributes, you can preserve any cart attributes with the checkout.attributes Liquid object, which contains the cart attribute values. You can loop through the attributes to add them as checkout attribute inputs with names and values defined by the existing attribute data.

This snippet should be included inside a JavaScript function for placing the attribute inputs inside the main form.

Example

{% for attribute in checkout.attributes %}
<input type=hidden name="checkout[attributes][{{ attribute.first }}]" value="{{ attribute.last }}" />
{% endfor %}

Was this page helpful?