Metal anvil representing in a strange way the authors heavy and painful process of modifying Shopify checkout template

Modifying Shopify Plus checkout.liquid Template

Shopify checkout.liquid can be a strange beast if you are new to the Plus platform.

This is not the typical Liquid template, it has few things you need to be aware of.

There are several steps in the checkout process: contact_information, shipping_method, payment_method, processing and thank you page. All of these steps are all happening on one page. The checkout content added trough this dynamic behaviour can be a challenge to modify.

Things to be aware:

  • All the checkout steps are on one checkout page: contact_information, shipping_method, payment_method, processing and thank you page.
  • Big chunks of markup. Checkout.liquid introduce new Liquid variables like content_for_order_summary. Those variables will return blocks of markup that can be hard to modify.
  • There are several JavaScript events and objects that will help development. Page:load and Page:change are events triggered by Shopify. Page:load will fire when the content of each step is loaded, Page:change will fire when something is dynamically changing the DOM, like submitting a discount coupon.
  • Shopify.Checkout.step JavaScript object returns the current checkout step. This is handy when you want to make changes on a particular step.

Keep in mind that changes done on checkout require maintenance. With each checkout update verify that your code still works as intended.

Modifying checkout.liquid

In Liquid, you can do String replacement to add/remove content but this is risky (you do not own the content) and unmaintainable. JavaScript gives more flexibility.

Let's assume we want to add a popup on a payment gateway. It's a commune case where merchants want to give more information about a particular payment option. This is a quick boilerplate code I use when doing checkout modifications:


(function CheckoutPaymentPopup() {
  'use strict';

  // Perform changes only on the payment_method step
  if (Shopify.Checkout.step !== 'payment_method') return;

  // Initialize after Shopify renders the checkout
  document.addEventListener('page:load', init);
  // Reinitialize on DOM refresh
  document.addEventListener('page:change', init);

  // Logic
  function init() {
    // Use data attributes for selector hooks
    var gatewayEl = document.querySelector('[data-select-gateway="32512116494"]');
  }
	
})();

My tips:

  • Wrap your code in an IFFY, do not leak your variables.
  • Detect the step using Shopify.Checkout.step, exit early.
  • Use page:load and page:change events. Page:change is the key here, you do not want your event listeners and DOM to disappear after the user adds a discount code.
  • Use data attributes not classes. We do not own that code but it's safer to assume that the data attributes added by Shopify are meant for this purpose.
  • Keep it clean, use snippets.