How do I track Ecommerce interactions using the Tag Manager data layer?

A flexible way to track Ecommerce interactions, such as add to cart, product views, and order completions, is to use Matomo Tag Manager with the mtm data layer.

The _mtm.push function pushes event data to the MTM data layer, such as product details and transaction values, enabling Tag Manager to trigger tags based on user interactions. Event types can be customised to represent any interaction, such as add_to_cart, purchase, remove_from_cart, view_item, view_item_list, or checkout.

Each event can include key properties that describe product or transaction details, such as id, name, category, price, quantity, and total.

This guide explains how to configure Matomo Tag Manager to track product and category views, Ecommerce orders and add to cart actions.

How to track Product Page views

Tracking how often a product page is viewed can provide insights into customer interest with specific products. The data is recorded and displayed in Matomo > Ecommerce > Products.

Push data to the MTM data layer

From your Ecommerce backend website/app (not in Matomo Tag Manager), trigger the Tag Manager view_item event to push the event data to the mtm data layer. This ensures the data layer is correctly structured and populated before creating variables, triggers, and tags in MTM.

window._mtm.push({
    'event': 'view_item',
    'ecommerce': {
        'items': [
            {
                'item_id': '67891',
                'item_name': 'Level 1-Contents',
                'item_category': 'Insurance',
                'item_price': '59.99'
            }
        ]
    }
});

After pushing the event data, use the browser’s Developer Tools Console command _mtm to check the data layer was populated.

Add a Data Layer Variable

This example uses the ecommerce data object. By creating a data layer variable, Matomo Tag Manager can dynamically access the values stored in ecommerce.

  1. Navigate to Tag Manager > Variables.
  2. Click Create New Variable and choose the Data Layer Variable type.
  3. Name it Ecommerce and set the Data Layer Variable Name (matching the name in the data layer object), e.g., ecommerce.
  4. Click Create New Variable to save.

Create a Custom Trigger and Tag

Create a trigger that fires when the view_item event is pushed to the mtm data layer. When the event is detected, the linked Custom HTML Tag executes to send Ecommerce data to Matomo.

  1. In Tag Manager, navigate to Triggers and click Create New Trigger.
  2. Choose the Custom Event Trigger and provide a descriptive name, e.g., Ecommerce Product View.
  3. Set the Event Name to view_item (matching the name in the data layer object).
  4. Click Create New Trigger to save. This trigger will fire when the view_item event is pushed to the data layer.
  5. Navigate to Tags and click Create New Tag.
  6. Choose the Custom HTML Tag and provide a descriptive name, e.g., Ecommerce Product View Tag.
  7. In the Custom HTML field, insert the script:
    Note: var ecommerce = {{Ecommerce}}; dynamically pulls the ecommerce object from the data layer using the Data Layer Variable named Ecommerce.
<script>
    window._paq = window._paq || [];
    var ecommerce = {{Ecommerce}}; // Ensure this variable is correctly populated 
    if (ecommerce && ecommerce.items && ecommerce.items.length) {

    // Push product view data for each item in the ecommerce object
    ecommerce.items.forEach(function(item) {
        // Push Ecommerce view data
        _paq.push(['setEcommerceView',
            item.item_id,          // Product ID (string or null)
            item.item_name,        // Product Name (string or null)
            item.item_category,    // Product Category (array or string)
            item.price             // Product Price (number or null)
        ]);

        // Optionally, log a custom event (e.g., for analytics purposes)
        _paq.push(['trackEvent', 'Ecommerce', 'View item', item.item_name, item.price]);
    });

    // Ensure you track the page view along with the Ecommerce data
    _paq.push(['trackPageView']);
</script>

Link the Custom Event Trigger and click Create New Tag to save.

Before publishing the changes live, test and validate the configuration before publishing.

How to track a Category Page view

Tracking category page views helps gain insights into customer interest in specific product categories, for example, Insurance or Subscriptions. The data will be recorded and displayed in Matomo > Ecommerce > Products.

Push data to the MTM data layer

From your Ecommerce backend website/app (not in Matomo Tag Manager), trigger the Tag Manager view_item_list event to push the event data to the mtm data layer. This ensures the data layer is correctly structured and populated before creating variables, triggers, and tags in MTM.

window._mtm.push({
    event: "view_item_list",
    ecommerce: {
        item_list_name: "Insurance"
    }
});

After pushing the event data, use the browser’s Developer Tools Console command _mtm to check the data layer was populated.

Add a Data Layer Variable

If you have not already created the ecommerce data layer variable, then follow these steps to add one now.

  1. Navigate to Tag Manager > Variables.
  2. Click Create New Variable and choose the Data Layer Variable type.
  3. Name it Ecommerce and set the Data Layer Variable Name (matching the name in the data layer object), e.g., ecommerce.
  4. Click Create New Variable to save.

Create a Custom Trigger and Tag

Create a trigger that fires when the view_item_list event is detected in the mtm data layer.

  1. In Tag Manager, navigate to Triggers and click Create New Trigger.
  2. Choose the Custom Event Trigger and provide a descriptive name, e.g., Ecommerce Category View.
  3. Set the Event Name to view_item_list.
  4. Click Create New Trigger to save.
  5. Navigate to Tags and click Create New Tag.
  6. Choose the Custom HTML Tag and provide a descriptive name, e.g., Ecommerce Category View Tag.
  7. In the Custom HTML field, insert the script:
<script>
    window._paq = window._paq || [];
    var ecommerce = {{Ecommerce}};

    // Push custom event
    _paq.push(['trackEvent', 'Ecommerce', 'View item list', 'ecommerce.item_list_name']);

    // Push ecommerce data
    _paq.push([
        'setEcommerceView',
        false, // Product name is not applicable for a category view.
        false, // Product SKU is not applicable for a category view.
        ecommerce.item_list_name
    ]);

    // You must also call trackPageView when tracking a category view
    //_paq.push(['trackPageView']);
</script>

Link the Custom Event Trigger and click Create New Tag to save.

Before publishing the changes live, test and validate the configuration before publishing.

How to track an Ecommerce order

Tracking an Ecommerce order captures completed transactions, including key data like order ID, total revenue, tax, shipping costs, discounts, and product details, to measure sales performance and revenue.

Push data to the MTM data layer

Within your Ecommerce backend website/app (not in Matomo Tag Manager), trigger the Tag Manager purchase event to push the event data to the mtm data layer. This ensures the data layer is correctly structured and populated before creating variables, triggers, and tags in MTM.

window._mtm = window._mtm || [];
window._mtm.push({
'event': 'purchase',
'ecommerce': {
  'purchase': {
    'id': 'dynamic value',
    'revenue': 'dynamic value',
    'orderSubTotal': 'dynamic value',
    'tax': 'dynamic value',
    'shipping': 'dynamic value',
    'discount': 'dynamic value',
    }
  }
});

Replace the dynamic value with the actual value for an Ecommerce interaction. After configuring Tag Manager, the purchase event will then trigger a Custom HTML tag to track the Ecommerce interaction in Matomo, using your data layer’s dynamic variables.

Add a Data Layer Variable

This example uses the ecommerce.purchase data object. By creating a data layer variable, Matomo Tag Manager can dynamically access the values stored in ecommerce.purchase.

  1. In Tag Manager, navigate to Variables.
  2. Click Create New Variable and choose the Data Layer Variable type.
  3. Provide a name such as PurchaseInfo and set the Data Layer Variable Name to ecommerce.purchase (matching the key name in your data layer object).
  4. Click Create New Variable to save.

Create a Custom Trigger and Tag

Create a trigger that fires when the purchase event is pushed to the mtm data layer. When the event is detected, the linked Custom HTML Tag executes and sends Ecommerce data to Matomo.

  1. In Tag Manager, navigate to Triggers.
  2. Click Create New Trigger and choose the Custom Event Trigger.
  3. Provide a name such as Ecommerce Purchase Trigger and set the Event Name to purchase (matching the key name in your data layer object).
  4. Click Create New Trigger to save. This trigger will fire when the purchase event is pushed to the data layer.
  5. Navigate to Tags and click Create New Tag.
  6. Choose the Custom HTML Tag and provide a name such as Ecommerce Order Tracking Tag.
  7. In the Custom HTML field, insert the script to track an Ecommerce order, for example:
<script>
window._paq = window._paq || [];
var purchaseInfo = {{PurchaseInfo}};
//console.log(purchaseInfo);
window._paq.push(['trackEcommerceOrder',
  purchaseInfo.id, // (required) Unique Order ID
  purchaseInfo.revenue, // (required) Order Revenue grand total (includes tax, shipping, and subtracted discount)
  purchaseInfo.orderSubTotal, // (optional) Order sub total (excludes shipping)
  (purchaseInfo.tax || 0), // (optional) Tax amount
  (purchaseInfo.shipping || 0), // (optional) Shipping amount
  (purchaseInfo.discount || false) // (optional) Discount offered (set to false for unspecified parameter)
]);
</script>

The tag uses the PurchaseInfo data layer variable (created previously). In this script, var purchaseInfo = {{PurchaseInfo}}; dynamically pulls the ecommerce.purchase object from the data layer using the Data Layer Variable named PurchaseInfo.

Link the Custom Event Trigger and click Create New Tag to save.

Before publishing the changes live, test and validate the configuration before publishing.

How to track Add to Cart actions

Tracking add to cart actions captures when visitors add items to their shopping cart, including key data like product ID, name, category, price, and quantity, which you can use to analyse user intent and product interest.

Push data to the MTM data layer

From your Ecommerce backend website/app (not in Matomo Tag Manager), you can trigger the add_to_cart event to push the event data to the mtm data layer. It ensures the data layer is correctly structured and populated before creating variables, triggers, and tags in MTM.

This example uses the following script to push the data to the mtm data layer.

<script>
window._mtm.push({
    'event': 'add_to_cart',
    'ecommerce': {
        'items': [
            {
                'item_id': '12345',
                'item_name': 'Premium Plan',
                'item_category': 'Subscription',
                'item_price': '29.99',
                'quantity': 1
            },
            {
                'item_id': '67891',
                'item_name': 'Level 1-Contents',
                'item_category': 'Insurance',
                'item_price': '59.99',
                'quantity': 2
            }
        ],
        'total': '89.98'
    }
});
</script>

Create a Custom Trigger and Tag

Create a trigger that fires when the add_to_cart event is pushed to the mtm data layer.

  1. In Tag Manager, navigate to Triggers and click Create New Trigger.
  2. Choose the Custom Event Trigger and provide a name such as Add to Cart Event Trigger.
  3. Set the Event Name to add_to_cart (matching the name in your data layer object).
  4. Click Create New Trigger to save. This trigger will fire when the add_to_cart event is pushed to the data layer.
  5. Navigate to Tags and click Create New Tag.
  6. Choose the Custom HTML Tag and provide a name such as Cart Items Tag.
  7. In the Custom HTML field, insert the script to track items added to the cart, for example:
<script>
//find the ecommerce element in the dataLayer
var ecommerceData = _mtm.find(function(item) {
    return item.event === "add_to_cart" && item.ecommerce && item.ecommerce.items;
});
if (ecommerceData) {
    var items = ecommerceData.ecommerce.items;
    // Loop through the items and track each one to Matomo
    items.forEach(function(item, index) {
        _paq.push(['addEcommerceItem',
            item.item_id,       // Product SKU (Required)
            item.item_name,     // Product Name (Optional)
            item.item_category, // Product Category (Optional)
            item.item_price,    // Product Price (Optional)
            item.quantity       // Product Quantity (Optional)
        ]);
    });

    // Track the cart update with the total value
    _paq.push(['trackEcommerceCartUpdate', ecommerceData.ecommerce.total]);
}
</script>

Link the Custom Event Trigger and click Create New Tag to save.

This script loops through the cart items and tracks each one in Matomo. Note: The script retrieves data dynamically from the data layer and does not require setting up a data layer variable.

Test and Validate the Configuration

Before finalising your configuration, test the script and verify the MTM setup:

Validate the Data Layer Variable

  1. Open your website and perform the relevant action (e.g., complete a purchase or add an item to the cart).
  2. Press F12 to open the browser’s Developer Tools Console.
  3. Inspect the _mtm data layer for the purchase or add_to_cart event and confirm they contain the expected properties.

Test the Custom Trigger and Tag

  1. Enable Preview and Debug Mode in Matomo Tag Manager.
  2. Reload your website and trigger events: view_item, view_item_list, purchase or add_to_cart.
  3. Confirm the trigger fires correctly and the tag executes without errors.
  4. Complete a transaction on your website and check your Matomo reports to confirm that the Ecommerce event data is being tracked.
Previous FAQ: How do I track Pageviews of my website using Matomo Tag Manager?