Overview

This article explains how to install the illumin Universal Pixel on Shopify, including theme implementation and Shopify-specific conversion tracking options.

You will learn how to:

• Add the Universal Pixel to your Shopify theme
• Implement a page event snippet for conversion tracking

This article covers Shopify implementation only. It does not explain how to create or map a Universal Pixel inside illumin.

Prerequisites

You'll need to create and copy an illumin Universal Pixel to implement sitewide and generate a page event snippet. This snippet goes on the final confirmation page that appears after a user makes a purchase. If you need assistance with the pixel or snippet after reviewing this article, contact your illumin Account Manager for assistance. 

Adding a Universal Pixel to a Shopify theme

The first step is to edit the store's current theme and implement the Universal Pixel to fire sitewide. Log in to the store, go to the sidebar menu, and click Online Store > Themes. Locate the current theme, click the three-dot icon, and select Edit code in the drop-down.

 

A new page displays. In the left menu, select theme.liquid and then go to the main window. Paste in Shopify after {{ content_for_header }} and before the closing </head> tag. Click Save and then click the Exit icon in the top left corner.

Placing the pixel and snippet in Shopify 

There are two ways to place the pixel and snippet in Shopify:

• Option 1: on the Checkout page
• Option 2: on the Customer events page

Option 1: on the Checkout page

On the main Shopify page, go to the bottom left corner and click the Settings icon.

 

On the General Settings page, click Checkout.

 

Scroll down to the Order status page field and locate the Additional Scripts field. To prevent the conversion pixel from firing multiple times when a user returns to the order status page, paste this conditional statement into the Additional Scripts field.

<!-- Conversion scripts you want to run only once →
{% if first_time_accessed %}
{% endif %}
<!-- Scripts you want to run on every visit → 

 

Then paste the illumin Universal Pixel in Shopify, followed by the page event snippet between {% if first_time_accessed %} and {% endif %}.

If you want to track order IDs and the associated revenue in illumin, and allow illumin to optimize for ROAS, include Shopify macros in the page event snippet. In the screenshot below, illumin can track revenue in the crev field and order IDs in the ordid field.

Shopify macros

• Order Id macro: {{ order_number }} 

OR

• Order ID macro: {{ order_id }} (depending on the Shopify store setup)
• Revenue (crev): {{ checkout.total_price | money_without_currency }}
• Note that checkout.total_price returns the total price of the checkout.

 

Note that Shopify will deprecate the Additional Scripts feature. It won't be supported after August 28, 2025. The Checkout page displays the following message:

• “Additional scripts is deprecated. Review your current customizations, then recreate the customizations you want to keep using pixels in customer events and app blocks in the editor."

Once the additional scripts page is no longer available, use Option 2. If you have already switched to the Customer events page, then go ahead with Option 2 right away.

If you move your script to the recommended Customer events block and encounter a problem, contact your illumin Account Manager. Our engineers will suggest script changes to solve the problem.

Option 2: on the Customer events page

On the main Shopify page, go to the bottom left corner and click the Settings icon. 

On the General Settings page, click Customer events.

 

Go to the top right corner of the page and click Add custom pixel. A pop-up displays. Enter a unique name and then click the Add pixel button. A code box displays.

 

Entering code

The following script is used specifically for Shopify Customer Events implementation.

Go to the code box and remove the default code. Then paste in the following illumin Universal Pixel code. Be sure to remove the placeholders (e.g. pixel codes and snippet page group ID ) and paste in your unique settings.

// Function to load the AcuityAds SDK 

(function(a, e) { 

   if (!a.aap) { 

       a.aap = function(e) { 

           (a.acuityAdsEventQueue = a.acuityAdsEventQueue || []).push(e); 

       };

 

       var script = e.createElement('script'); 

       script.async = true; 

                 script.src = 'https://origin.acuityplatform.com/event/v2/pixel.js'; 

                 var firstScript = e.getElementsByTagName('script')[0];

                 firstScript.parentNode.insertBefore(script, firstScript);  

 

       a.acuityPiggybackCallback = function(e) { 

           a.acuityParseResponse(e); 

       };

   }

})(window, document); 

 

// Initialize the AcuityAds Pixel with your pixelKey 

aap({ pixelKey:'Your Universal Pixel Key' e.g. '6654652000422993785' }); 

 

// Subscribe to Shopify's checkout completed event 

analytics.subscribe('checkout_completed', function(event) { 

      // Extract total price and order ID from the event data 

   var totalPrice = event.data.checkout.totalPrice?.amount; 

   var orderid = event.data.checkout.order?.id; 

 

   // Send the data to AcuityAds 

   aap({ 

       pixelKey: 'Your Universal Pixel Key' e.g. '6654652000422993785', 

       pg: Your Conversion Snippet Page Group ID, e.g. 40646, 

       crev: totalPrice, 

       ordid: orderid 

   });

});

 

Shopify macros

• Order Id macro: event.data.checkout.order?.id 
• Revenue (crev): event.data.checkout.totalPrice?.amount  

 

illumin Conversion Pixel Tag example 

To complete the setup and connect the pixel to your Shopify store, click Save, and then Connect. 

 

---

FAQs

How does the pixel support retargeting?

The Universal Pixel records page visits and purchase behavior across the store. This lets marketers build retargeting audiences based on real actions and improve follow up messaging.

Why might revenue values fail to appear in illumin reports?

Revenue may not pass if the macro returns a null value or the snippet references the wrong field. Confirm that the store uses the correct macro format and that the Page Group ID matches the intended conversion event.

What changes when Shopify removes the Additional Scripts field?

Shopify plans to retire this method and move all tracking to Customer events. Marketers should migrate conversion code to the new pixel framework to keep reporting consistent.

When should a marketer contact an illumin Account Manager?

Reach out when the pixel does not fire, revenue stays at zero, or order IDs fail to pass. An Account Manager can confirm setup details and advise on code adjustments.