Best practices for editing checkout.liquid

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, then they could break with new upgrades. It’s always best to minimize DOM dependency to reduce future support debt for your team.

When making changes, you should 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.

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.

In general, the approach for making customizations is the following:

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

The following examples show a killswitch theme setting and a snippet inclusion wrapped in a conditional based on the killswitch:

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 following objects:
  • Shopify.Checkout.step
  • Shopify.Checkout.page
  • Shopify.Checkout.OrderStatus

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.

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

To block the use of specific characters in address fields, you need to consider the following cases:

1. Updates to the associated address fields, such as the blur event.

2. The form submit event.

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

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

The maxlength attribute only prevents additional characters from being entered. To ensure a good user experience, you should add a message that appears when a customer hits the character limit.

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.