Guide to Migrating the Thank You and Order Status Pages: Why, When, and How to Do It

Confirming if you need to migrate

Shopify provides an AI-generated report that analyzes existing customizations, categorizes them, and offers suggestions on how to update them. This personalized guide helps identify the modifications present on the Thank You and Order Status pages, providing detailed instructions on how to recreate them within the new system.

How to access the guide:

1. In the Shopify admin, navigate to Settings > Checkout.

2. In Settings click on Review Customizations.

3. In the Customization report, you will get information about the upgrade, broken down into different categories:
   
   
   1. Installed Apps: List of apps that already offer blocks for the Thank You Page and Order Status Page, or app pixels to manage specific tracking needs. In this case, activation or configuration will be required.
      
   2. Incompatible Apps: A list of apps that are currently not compatible with the new infrastructure. Shopify recommends contacting the app's support team for more information on potential updates.
   3. Additional Scripts: Using an AI model (LLM), Shopify analyzes the code present in the Additional Scripts section, provides an explanation of its functionality, and suggests how to migrate it to the new system.
      

      
      

In addition, if you are a Shopify Plus merchant and you had customizations like upsell or surveys within the thank you and order status page, you need to consider how to migrate these using Checkout UI extensions.

When your upgrade guide is empty, you can proceed directly with replacing the pages to publish your new customizations. This will be done within the checkout editor and it's simply done by clicking a button.

Our Reflections on the Migration

When we first started exploring the customization of Shopify’s Thank You Page and Order Status Page, the available tools and options were still quite limited, giving the impression of a feature in its early stages. Over time, however, Shopify has introduced significant updates, improving the flexibility of these pages, especially with the introduction of the Pixel Helper tool.

The Pixel Helper has been a crucial addition, as it allows developers to visualize the available data for each event, simplifying debugging and ensuring the correct activation of marketing pixels. This tool has certainly made the migration more intuitive, but there is still a lot of work to be done to ensure that all custom pixels are migrated correctly and that the necessary event data is tracked comprehensively and accurately.

Within Custom Pixels, Shopify has also introduced customer privacy permission settings, allowing merchants to manage with greater granularity what type of data can be collected based on user preferences.

Tracking: Migration Approach Examples

Most of the customizations I have migrated involve tracking implementations through additional scripts. Below are some examples of how to handle this migration effectively to ensure that pixels and tracking systems continue to function properly.

Shopify recommends carrying out the migration during a low-traffic period to minimize the risk of data duplication or loss during the transition.

GTM

One of the most comprehensive migration examples provided by Shopify is Google Tag Manager (GTM) – here is the documentation. 

Shopify generates events whenever a user interacts with store pages, such as viewing a product, navigating a page, or adding an item to the cart. By leveraging these native events, it is possible to send the necessary data to GTM’s dataLayer. However, since the available data is limited to what Shopify exposes, there are some restrictions.

For example, it is no longer possible to retrieve specific customer details, such as the number of past orders they have placed. This requires careful consideration of alternative ways to obtain this data—or, more fundamentally, assessing whether it is truly essential for tracking and analytics.

Other tracking scripts

In the Custom Pixel migration Guide, the step-by-step process for migrating scripts such as Google Analytics is outlined. Most of these tracking implementations start with a <script> tag that calls an external script within the Thank You page.

With custom pixels, it is no longer possible to insert HTML directly into the Thank You page. Instead, the script must be injected using JavaScript. As explained by Shopify:

<script async src="https://www.googletagmanager.com/gtag/js?id=YOUR_PIXEL_ID"></script>

will become

const script = document.createElement('script');
script.setAttribute('src', 'https://www.googletagmanager.com/gtag/js?id=YOUR_PIXEL_ID');
script.setAttribute('async', '');
document.head.appendChild(script);

Then, within this Pixel, we will pass the data made available by Shopify events in the format required by the tracking system.

How to gather data not available through Shopify's events

As mentioned earlier, the data we can pass to our tracking systems depends on what Shopify makes available. However, in some cases, additional information can be retrieved using alternative strategies.

A particularly effective example is provided by Clerk.io, which utilizes local storage to transfer product data that the user viewed before completing checkout. Local storage allows this information to be stored directly in the user's browser, eliminating the need to reload it from external databases or make additional API calls. This makes it an efficient solution for handling data that Shopify does not natively provide.

Specifically, the theme’s code emits a custom event, which is then "listened to" within a custom pixel. You can find detailed documentation on this type of pixel in Clerk.io’s installation guide for Shopify. 

Conclusion

The migration of the Thank You Page and Order Status Page represents a significant shift for Shopify merchants, but also an opportunity to modernize and optimize existing customizations. Preparing for this transition in advance will help prevent disruptions in order tracking, marketing pixels, and checkout customizations.

By adopting solutions such as Google Tag Manager, local storage, and app blocks, merchants can maintain a high level of functionality while aligning with Shopify's new guidelines.

For developers, this transition is a chance to enhance tracking efficiency and improve integration with analytics tools. Staying up to date with Shopify’s best practices and carefully testing each change will ensure a seamless migration, keeping the store's customer experience smooth and optimized.