Manual Ecommerce Tracking: Quick Start

This guide provides an example of how to manually implement Ecommerce tracking for a site which uses a custom Ecommerce platform. If you are using an Ecommerce platform that is not custom built, such as WooCommerce, please check our Ecommerce integrations page to see if an integration method or plugin already exists for your platform. We also provide an integration guide for Shopify.

This guide is written for use with the JavaScript tracking client, however tracking calls included in this guide can be incorporated into your webpage via the Matomo Tag Manager using a Custom HTML Tag.

Getting Started

For ease of tracking Ecommerce actions, it is recommended to include all cart items within a single JavaScript variable such as cartProducts. This will allow you to loop through the items when reporting Ecommerce actions to Matomo. Here is an example of how your variable might be created. You would need to use custom script to assign the correct details for each product…

//array containing all items in the cart along with product details
var cartProducts = [
{
    productSKU: "0123456789",
    productName: "Ecommerce Analytics Book",
    productCategory: ["Books", "Best sellers"],
    price: 9.99,
    quantity: 1
},
{
    productSKU: "9876543210",
    productName: "Product 2",
    productCategory: ["Electronics", "Gadgets"],
    price: 19.99,
    quantity: 2
},
{
    productSKU: "4567891230",
    productName: "Product 3",
    productCategory: ["Clothing", "T-Shirts"],
    price: 14.99,
    quantity: 3
},
{
    productSKU: "7890123456",
    productName: "Product 4",
    productCategory: ["Toys", "Kids"],
    price: 24.99,
    quantity: 2
}
];

Managing Cart Items

Keeping track of cart inventory requires maintaining a list of cart items server-side. This provides the ability to create the cartProducts variable with each new page load. If a customer does not yet have items in their cart it is still a good idea to keep track of the empty cart by assigning an empty array to cartProducts. This will allow you simply push a new product to the array whether or not there are existing items, preventing the need to check if the array exists before adding an item.

There are two ways to manage cart items in Matomo:
1. Manage changes to individual items by only tracking the items that are reduced in quantity, removed or are added to the cart.
2. Clear all cart items in Matomo and track the full list of cart items with each cart update.

For the simplicity of this guide and implementation, option 2 is used below.

Tracking Ecommerce Actions

Now that you have a variable containing all of your customer’s cart items, let’s look at how we can track these items to Matomo. The script below will loop through each item and call the method addEcommerceItem while providing product details. It then aggregates the total value of all items in the cartProducts variable and finally calls the method trackEcommerceCartUpdate to send the cart data to Matomo…

//reset the cart items in Matomo
_paq.push(['clearEcommerceCart']);

//loop through each item to report cart data to Matomo
cartProducts.forEach(function(product) {
    _paq.push(['addEcommerceItem',
    product.productSKU,
    product.productName,
    product.productCategory,
    product.price,
    product.quantity
]);
});

//calculate the sum total of all cart items
var totalCartValue = cartProducts.reduce(function(total, product) {
    return total + (product.price * product.quantity);
}, 0);

//push the cart data to Matomo
_paq.push(['trackEcommerceCartUpdate', totalCartValue]);

For tracking the order, we can use the same cart value as calculated in the previous step when calling the trackEcommerceOrder method. If you need to add tax or shipping cost, provide a value for these within this call…

_paq.push(['trackEcommerceOrder',
    "000123", // (Required) orderId
    totalCartValue, // (Required) grandTotal (revenue)
    0, // (Optional) subTotal
    0, // (optional) tax
    0, // (optional) shipping
    false // (optional) discount
]);

Tracking Product Views

Tracking product views can work in a similar way to tracking cart times. When a product page is loaded, pass the product details to a variable named viewProduct, for example. This variable would contain details for the viewed product. For instance…

var viewProduct = {
    name: "Neon Lamp",
    sku: "SKU1",
    category: ["Category1", "Subcategory1"]
};

Just before tracking the page view, call the setEcommerceView method while passing the details from your variable…

//set the commerce view
_paq.push(['setEcommerceView',
    viewProduct.name, // Product name is not applicable for a category view.
    viewProduct.sku, // Product SKU is not applicable for a category view.
    viewProduct.category, // Product category, or array of up to 5 categories
]);

//you must call trackPageView when tracking an Ecommerce view
_paq.push(['trackPageView']);

Learn More

This guide should provide a basic understanding of the framework required to track Ecommerce actions in Matomo with a custom Ecommerce platform. Please also see our Advanced: Manual Ecommerce Tracking Guide for more information about the methods discussed above and other Ecommerce methods available with Matomo.