checkout.liquid

For merchants on Shopify Plus, the checkout process is rendered by the checkout.liquid file. Unlike theme.liquid, checkout.liquid is self-contained and does not render any additional template files. The checkout process includes the following steps:

Step Description
Inventory issues This 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.
Customer information The 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, the customer will be shown a shipping address form. Otherwise, the customer is shown a billing address form.
Shipping method The customer selects a shipping option or edits shipping info. 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 method The 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 may be required if operating in the European Union. Learn more ›
Processing/forwarding A 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 status The last step of checkout, 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 (collapses on mobile).

Template considerations

Enabling access to checkout.liquid

There are 2 versions of checkout:

  1. Standard - this version is the default which is used if access to checkout.liquid is not enabled, and it will be automatically updated as Shopify releases new updates and features for the checkout.

  2. Maintenance - this version is used when access to checkout.liquid is enabled, and is a stable version of the Standard checkout, frozen at a specific time. This means that it's not automatically updated, so your options for getting new updates and features are to:

- Disable access to checkout.liquid to move back onto the Standard version - Wait for the Maintenance version to be upgraded and follow the checkout upgrade process

Required objects

There are two Liquid objects that are required in checkout.liquid:

  1. {{ content_for_header }} - this object must be placed between the opening and closing <head> tag. It inserts the necessary Shopify scripts into the <head> which includes scripts for Google Analytics, Shopify analytics, Shopify apps, and more.

  2. {{ content_for_layout }} - this object must be placed between the opening and closing <body> tag. It dynamically outputs the form fields and content for each step of the checkout process.

Optional objects

You can also reference the following objects in the checkout.liquid template:

  • {{ locale }} : The currently selected locale.
  • {{ direction }} : The CSS direction of the content. For example, ltr or rtl.
  • {{ page_title }} : The page title (commonly wrapped in <title> tags).
  • {{ skip_to_content_link }} : A hidden link for accessibility allowing users to skip to the main content.
  • {{ checkout_html_classes }} : A string that should be added to the HTML tag to benefit from our default CSS.
  • {{ checkout_stylesheets }} : Shopify's checkout stylesheets. It's recommended that you don't remove this, even if you have your own stylesheets, as it would require extensive work to replace the default styling.
  • {{ checkout_scripts }} : Shopify's Javascript files.
  • {{ content_for_logo }} : Your shop logo, as determined by your theme customizations.
  • {{ breadcrumb }} : The list of steps required to complete the checkout. The breadcrumb does not display on the final review step during checkout.
  • {{ order_summary_toggle }} : The markup necessary to show and hide the order summary on mobile devices.
  • {{ content_for_order_summary }} : The content summary, including line items, discounts, taxes, and totals.
  • {{ alternative_payment_methods }} : The list of express methods available, such as PayPal.
  • {{ content_for_footer }} : The list of your shop policies or, if the list is empty, a copyright notice.
  • {{ tracking_code }} : The Javascript code that lets you track the checkout with Google Analytics.
  • The {{ checkout }} Liquid object.

Customizing

The content generated by any of the above objects (required or optional) can't be edited before being rendered, except for translation settings, theme editor settings, and some options made available in the store's admin.

Step Identification

The checkout is all hosted on one page, so the URL remains the same, regardless of which step of the process a customer is on. There are Javascript objects to define where the customer is in the checkout process, which can be viewed using your browser's developer tools.

Shopify.Checkout.step

An object that shows which step of the checkout the customer is on, and will return one of the below results:

  • contact_information
  • shipping_method
  • payment_method
  • processing (between the payment_method step and the thank_you page)
  • review (an optional step set in the Shopify Admin)

Shopify.Checkout.page

An object that shows which type of page the customer is on. It returns one of the below 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

Shopify.Checkout.OrderStatus

An object that can be used for adding content to the Order Status page. It also can 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.

Page Events

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

Page:load

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

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

Page:change

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.

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

Checkout jQuery

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

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

Checkout attributes

Capture checkout attributes

You can capture checkout attributes in a similar way to capturing cart attributes. To capture a checkout attribute, include the attribute input inside the main form with a name attribute of checkout[attributes][attribute name]. The following code example adds a text input that captures a custom attribute.

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

Preserve 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 to add them as checkout attribute inputs with names and values defined by the existing attribute data.

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