How do I install the Matomo tracking code using Shopify custom pixels (NEW) FAQ - New to Matomo

All Shopify merchants can install the Matomo tracking code using the recommended custom pixel in Shopify’s Customer Events. This guide replaces previous Matomo-Shopify integration configurations.

Upgrade to Shopify’s Checkout Extensibility

If you are on a Shopify Plus plan upgrading from checkout.liquid with an existing Matomo integration, read this section before creating a Shopify custom pixel.

As of 13 August 2024, Shopify will be deprecating the usage of checkout.liquid to introduce custom code to your checkout. The script tags and additional scripts for the Thank You and Order status page are also affected and will be turned off from August 2025. Learn more from Shopify about the impact on your store.

Shopify Plus merchants who customised their checkout with checkout.liquid need to upgrade to Checkout Extensibility and reconfigure Matomo’s tracking using the Custom Pixel feature.

To simplify the review of your existing Matomo checkout customisations and to help you upgrade faster, use the Shopify Admin Customizations Report available under My Shopify Store > Settings > Checkout.
Remove or modify any existing tracking code to ensure customer events are not counted twice. Ensure it is removed from every place it exists as well as in the Additional scripts in your checkout settings.
Complete the Checkout Extensibility upgrade as specified in the official Shopify documentation.
Create a custom pixel to integrate Matomo Analytics with your Shopify store.

Create a Shopify custom pixel

The custom pixel functionality in Shopify is a simple way of adding your Matomo JavaScript Tracker directly in your store. Pixels are a secure way to plug customer events for accurate and relevant analytics reporting.

When you add a custom pixel to Shopify, you will insert the Matomo JavaScript tracking code and the behavioural events you want to track in one code block. This is an advanced feature that requires knowledge of JavaScript.

Prepare the Matomo tracking code

Find your Matomo tracking code in Matomo Administration settings > Measurables > Tracking code and copy to any editor or notepad.
Shopify’s sandbox only supports JavaScript, so remove the HTML from the tracking code and check your variables (Matomo URL, IDSITE) are inserted.

Add the custom pixel

Go to your Shopify store > Settings > Customer events to create and manage your pixels.
Click the Add custom pixel button and enter a Pixel name e.g. Matomo.
Save by clicking Add pixel and you will automatically be directed to the pixel’s configuration page.

Configure the custom pixel

In the configuration page, you can define the customer privacy settings, add the Matomo tracking code, and subscribe to events.

Expand the Customer privacy section to setup the required (1) Permission settings for Marketing and Analytics, (2) Data sale options (relevant to data protection law), and use (3) Customer privacy link to setup your privacy policy, cookie banner, and opt-out page.
In the Code section of the configuration page, you will add your (1) Matomo tracking code and (2) subscribe to events you want to track.

Note: For new Matomo installations, you need to complete and test the Matomo setup before configuring the tracking code. Copy the tracking code from the editor or notepad and paste it into the Shopify code block; click Save and Connect pixel. Test your Matomo installation is successful and then continue with the steps below.
With your Matomo instance up and running, ensure the tracking code is added to the top of the Shopify code block.
Delete _paq.push(['trackPageView']); and any HTML and event triggers.
Use the Shopify Pixels Extension API to insert and adapt the API reference code to subscribe to events. This will ensure the pixel is defined to collect the right data.
Once configured, click Save and then click Connect pixel to give Matomo secure access to customer events in your online store.

Track Shopify Ecommerce Actions in Matomo

For ecommerce tracking, it is recommended to subscribe to the following minimum standard events:

Page_viewed event logs an instance where a customer visited a page.
Checkout_completed logs an instance where a visitor completes a purchase.
Collection_viewed logs an instance where a customer visited a product collection index page.
Product_viewed logs an instance where a customer visited a product details page.
Product_added_to_cart logs an instance where a customer adds a product to their cart.
Cart_viewed logs an instance where a customer visited the cart page.

Below is an example of custom pixel code configured for ecommerce tracking:

var _paq = window._paq = window._paq || [];

_paq.push(['enableLinkTracking']);

(function() {
    var u="https://xxxx.matomo.cloud/"; // replace xxxx with the correct domain
    _paq.push(['setTrackerUrl', u+'matomo.php']);
    _paq.push(['setSiteId', '1']);
    var d=document, g=d.createElement('script'), s=d.getElementsByTagName('script')[0];
    g.async=true; 
    g.src='//cdn.matomo.cloud/xxxx.matomo.cloud/matomo.js'; 
    s.parentNode.insertBefore(g,s);
})();

analytics.subscribe("page_viewed", (event) => {
  window._paq.push(['setCustomUrl', event.context.window.location.href]);
  window._paq.push(['trackPageView']);
});

analytics.subscribe("checkout_completed", (event) => {

  const checkout = event.data.checkout;

  for (let index=0; index < checkout.lineItems.length; ++index) {
    const line_item = checkout.lineItems[ index ];
    window._paq.push(['addEcommerceItem',
      line_item.variant.id, // (Required) productSKU
      line_item.title, // (Optional) productName
      line_item.variant.product.type, // (Optional) productCategory
      line_item.variant.price.amount , // (Recommended) price
      line_item.quantity  // (Optional, defaults to 1) quantity
    ]);
  }

  window._paq.push(['trackEcommerceOrder',
     checkout.order.id , // (Required) orderId
     checkout.totalPrice.amount , // (Required) grandTotal (revenue)
     checkout.subtotalPrice.amount  , // (Optional) subTotal
     checkout.totalTax.amount , // (optional) tax
     checkout.shippingLine.price.amount , // (optional) shipping
     0 // (optional) discount
  ]);

});

analytics.subscribe("collection_viewed", (event) => {
  window._paq.push(['setEcommerceView',
      false, // Product name is not applicable for a category view.
      false, // Product SKU is not applicable for a category view.
      event.data.collection.title , // Product category
  ]);
});

analytics.subscribe("product_viewed", (event) => {
  window._paq.push(['setEcommerceView',
      event.data.productVariant.id, // (Required) productSKU
      event.data.productVariant.title, // (Optional) productName
      event.data.productVariant.product.type, // (Optional) categoryName
      event.data.productVariant.price.amount // (Optional) price
  ]);
});

analytics.subscribe("product_added_to_cart", (event) => {
  window._paq.push(['addEcommerceItem',
     event.data.cartLine.merchandise.product.id, // (Required) productSKU
     event.data.cartLine.merchandise.product.title, // (Optional) productName
     event.data.cartLine.merchandise.product.type, // (Optional) productCategory
     event.data.cartLine.merchandise.price.amount, // (Recommended) price
     event.data.cartLine.quantity // (Optional, defaults to 1) quantity
   ]);
  window._paq.push(['trackEcommerceCartUpdate', event.data.cartLine.cost.totalAmount.amount]);
});

analytics.subscribe("cart_viewed", (event) => {

  for (let index=0; index < event.data.cart.lines.length; ++index) {
    const line_item = event.data.cart.lines[ index ];
    window._paq.push(['addEcommerceItem',
      line_item.merchandise.product.id, // (Required) productSKU
      line_item.merchandise.product.title, // (Optional) productName
      line_item.merchandise.product.type, // (Optional) productCategory
      line_item.merchandise.price.amount , // (Recommended) price
      line_item.quantity  // (Optional, defaults to 1) quantity
    ]);
  }
  window._paq.push(['trackEcommerceCartUpdate', event.data.cart.cost.totalAmount.amount]);
});

Manage the status of the custom pixel

When custom pixels are created and saved, ensure the pixel is connected to the Shopify store. You can disable the pixel by choosing Disconnect. The pixel will no longer function but will be stored in the Disconnected Pixels section where you can connect it at any time in the future. To permanently remove the pixel from your Shopify store, click the ellipsis icon and select Delete.

Next FAQ: How do I install the Matomo tracking code on my Shopify store?