All Tutorials

Best practices for editing checkout.liquid

All Tutorials

Best practices for editing checkout.liquid

Best practices for editing checkout.liquid

If you're on Shopify Plus, then you can get access to the checkout.liquid template. However, if you make changes to this template, then you'll need to manually upgrade it whenever Shopify releases an upgrade.

Document Object Model (DOM) dependency

One of the biggest considerations to make when implementing checkout modifications is how DOM-dependent your code is. As Shopify releases checkout upgrades, the content output by the Liquid drops in checkout.liquid (and in some cases by the checkout.liquid content itself) is updated. This means that if your customizations depend on that content, they could break with new upgrades. It’s always best to minimize DOM dependency to reduce future support debt for your team.

Adding custom code

When making changes, it's good to keep all of the relevant code for a specific customization in a single snippet. This reduces the risk of conflict with other code, and generally makes the code easier to read.

Also, any time that a change is made, it's recommended that you place a comment at the beginning of the change noting who made it, and when, like the following example:

{% comment %} Added by Name from Company on September 21 2018 {% endcomment %}

Adding killswitches

When customizing checkout.liquid, you're more likely to run into issues or conflicts in the checkout, possibly preventing sales, so it's a good idea to wrap your customizations in a killswitch (a theme setting). This allows you to temporarily disable the customization to get the checkout functioning quickly, which gives you time to troubleshoot issues.

General customization approach

In general, the approach for making customizations is to:

  • Create a killswitch theme setting
  • Create a snippet to host your customization
  • Include your snippet, wrapped in your killswitch, in checkout.liquid

The following example shows a killswitch theme setting (in settings_schema.json):

  "type": "checkbox",
  "id": "checkout_customization",
  "label": "Enables a checkout customization"

The following example shows killswitch code wrapped around a snippet (in checkout.liquid):

{% comment %}Added by Name at Company on September 21, 2018{% endcomment %}
{% if settings.checkout_customization %}
  {% render 'checkout-customization' %}
{% endif %}

In your snippet, you can do the following:

  • Use the checkout's version of jQuery
  • Watch for the page:load and page:change events to set up your customization
  • Scope your customization to the appropriate step or page (by referencing the Shopify.Checkout.step,, and/or Shopify.Checkout.OrderStatus objects)
(function($) {
  $(document).on("page:load page:change", function() {
    if (Shopify.Checkout.step === "contact_information") {
      // Add content

Form submit

Many checkout customizations require validating data before allowing the customer to move to the next step. Due to the functionality around the main form submit button, the easiest approach is watch for the click event on this button, rather than the submit field on the form. You should also watch for the use of the enter key and re-route that functionality into a click event on the submit button.

(function($) {
  $(document).on("page:load page:change", function() {
    if (Shopify.Checkout.step === "contact_information") {
      $("DEFINE_YOUR_SUBMIT_BUTTON_SELECTOR").on("click", function(e) {

        if (data is valid) {
        } else {
          // Show an error

      $("DEFINE_YOUR_MAIN_FORM_SELECTOR").on("keyup", function(e) {
        if (e.keycode === 13) {

Common customizations

The following examples are commonly requested customizations. They all use the General customization approach as a starting point.

Block the use of specific characters in address fields

There are 2 aspects to this:

  1. Watch for updates to the associated address fields, such as the blur event.

  2. Watch for the form submit event.

For each of these, execute your validation. For example, you could compare any field values with a Regular Expression (Regex). Then, if the data isn't valid, show an error and prevent the default functionality.

Limit the number of characters in address fields

To limit the number of characters in address fields, add a maxlength attribute to any associated fields, as shown in the following example.

$("DEFINE_YOUR_FIELD_SELECTOR").attr("maxlength", your_value);

Also, for a good user experience, you should add a message that appears when a customer hits the character limit, as the maxlength attribute will only prevent additional characters from being entered.

Add a required Terms of Service checkbox

To add a required checkbox for agreeing to Terms of Service, create a checkbox on the page, then follow the form submit event to check whether the checkbox has been checked before allowing the customer to proceed. It's also a good idea to use a checkout attribute to save the value of the checkbox.