Advanced: Manually Tracking Ecommerce Actions in Matomo

If your website isn’t powered by a content management system or ecommerce platform that integrates with Matomo, then it may need to be manually integrated. You can manually integrate Matomo with any cart software by adding snippets of JavaScript code to your checkout process. The code, described below, sends your user’s shopping cart data to Matomo to track key actions for your analytics.

There are several categories of actions that you will need to integrate for a full Ecommerce tracking setup within Matomo:

  • Product Views (Optional) – This enables per-product conversion rates.
  • Cart Updates (Optional) – This enables tracking abandoned cart statistics.
  • Order Updates (Required) – This is a required component of Ecommerce tracking.

Tracking Product Views in Matomo (Optional)

By default, Matomo can let you know your conversion rate for your website as a whole. Additionally you can track how many people have visited a page where your product is available for sale. Then Matomo will automatically calculate a product conversion rate for each product.

Collecting product and category specific conversion rates can be helpful to identify where certain products may not have enough information, or where specific product categories are under-performing on your site.

There is one JavaScript method for pushing both products and category view data to Matomo, and that is 'setEcommerceView'. The only difference between tracking products and categories is which parameters are attached to the call. For both, you will also need to make sure that you include a 'trackPageView' call. You can find more details and examples for both below.

Tracking Product Views in Matomo

The following parameters are recommended for tracking product views:

  • productSKU (Required) – String – A unique product identifier.
  • productName (Required) – String – The name of the product.
  • categoryName (Optional) – String/Array – This is either the category name passed as a string, or up to five unique categories as an array, e.g. ["Books", "New Releases", "Technology"]
  • price (Optional) – Integer/Float – The cost of the item.

Example Product View Snippet

// Push Product View Data to Matomo - Populate parameters dynamically
_paq.push(['setEcommerceView',
    "0123456789", // (Required) productSKU
    "Ecommerce Analytics Book", // (Optional) productName
    "Books", // (Optional) categoryName
    9.99 // (Optional) price
]);

// You must also call trackPageView when tracking a product view 
_paq.push(['trackPageView']);

Tracking Category Views in Matomo

The following parameters are required and recommended for tracking a category pageviews (not a product page):

  • productSKU – Boolean – This should be equal to false.
  • productName – Boolean – This should be equal to false.
  • categoryName (Required) – String/Array – This is either the category name passed as a string, or up to five unique categories as an array, e.g. ["Books", "New Releases", "Technology"]

Example Category View Snippet

// Push Category View Data to Matomo - Fill category dynamically
_paq.push(['setEcommerceView',
    false, // Product name is not applicable for a category view.
    false, // Product SKU is not applicable for a category view.
    "Books", // (Optional) Product category, or array of up to 5 categories
]);

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

Tracking Cart Updates in Matomo (Optional)

To track cart additions and removals, your cart system will need to send the details for every item that remains in the cart after a user adds or removes an item, including those already submitted from prior Add to Cart clicks. This is important to collect accurate information for the abandoned cart feature within Matomo. The data should be included within a “push”, which is the function that enables sending of structured data to Matomo via JavaScript. You will also need to supply the total value of all items in the cart. so the two required elements for cart tracking are:

  • A push of 'addEcommerceItem' for each product currently in the cart, including the name and SKU at a minimum.
  • A final 'trackEcommerceCartUpdate' push with the cart total passed as a parameter.

Example Product Cart Update

Each item processed as part of the cart update can contain the following parameters but must include the name and SKU at a minimum.

  • productSKU (Required) – String – A unique product identifier.
  • productName (Recommended) – String – The name of the product.
  • categoryName (Optional) – String/Array – This is either the category name passed as a string, or up to five unique categories as an array e.g. ["Books", "New Releases", "Technology"]
  • price (Optional) – Integer/Float – The cost of the item.
  • quantity (Optional) – Integer – How many of this item are in the cart. Defaults to 1.

The snippet below contains example data in the format required by Matomo. All of the parameters should be dynamically filled by your ecommerce platform.

// An addEcommerceItem push should be generated for each cart item, even the products not updated by the current "Add to cart" click.
_paq.push(['addEcommerceItem',
    "0123456789", // (Required) productSKU
    "Ecommerce Analytics Book", // (Optional) productName
    ["Books", "Best sellers"], // (Optional) productCategory
    9.99, // (Recommended) price
    1 // (Optional, defaults to 1) quantity
]);

// Pass the Cart's Total Value as a numeric parameter
_paq.push(['trackEcommerceCartUpdate', 15.5]);

Tracking Orders to Matomo (Required)

Tracking orders is the minimum required configuration for a successful ecommerce tracking implementation. Order metrics are likely to be the most valuable for any ecommerce store, so you need to make sure that you set up order tracking correctly.

There are two main elements required to push an ecommerce purchase to Matomo:

  • Product details for each product purchased, containing the Product SKU at a minimum.
  • Order details; containing a unique order ID and the total revenue at a minimum.

The order is typically tracked on the order confirmation page after payment has been confirmed.

Note: The unique order ID generated by your cart software ensures the same order isn’t tracked twice.

Example of Adding a Product to the order

The snippet below contains example data in the format required by Matomo. All of the parameters, which are shown within double quotation marks, should be dynamically filled by your ecommerce platform.

  • productSKU (Required) – String – A unique product identifier.
  • productName (Recommended) – String – The name of the product.
  • productCategory (Optional) – String/Array – This is either the category name passed as a string, or up to five unique categories as an array, e.g.
    ["Books", "New Releases", "Technology"]
  • price (Optional) – Integer/Float – The cost of the item.
  • quantity (Optional) – Integer – How many of this item are in the order. Defaults to 1.

The Code Example:

// Product Array
_paq.push(['addEcommerceItem',
  "01234567890", // (required) SKU: Product unique identifier
  "Ecommerce Analytics Book", // (optional) Product name
  "Books", // (optional) Product category. You can also specify an array of up to 5 categories eg. ["Books", "New releases", "Biography"]
  9.99, // (Recommended) Product Price
  1 // (Optional - Defaults to 1)
]);

Example of Tracking the Ecommerce Order

The second part of the order update code passed to Matomo is a summary of the order. At a minimum, it should include an order ID and the total revenue value. The variables passed, in order, are:

  • orderId (Required) – String – A unique reference number to avoid duplication.
  • grandTotal (Required) – Integer/Float – The order total revenue including tax & shipping with any discounts subtracted.
  • subTotal (Optional) – Integer/Float – The order total excluding shipping.
  • tax (Optional) – Integer/Float -The amount of tax charged.
  • shipping (Optional) – Integer/Float – The amount charged for shipping.
  • discount (Optional) – Integer/Float/Boolean – Discount offered? Default to false. Otherwise, you should include a numeric value.

The Code Example:

// Order Array - Parameters should be generated dynamically
_paq.push(['trackEcommerceOrder',
    "000123", // (Required) orderId
    10.99, // (Required) grandTotal (revenue)
    9.99, // (Optional) subTotal
    1.5, // (optional) tax
    1, // (optional) shipping
    false // (optional) discount
]);

Developer Warning: Currency Variables must be passed as an Integer or Float

The following currency parameters must be supplied as integers or floats, not as strings:

  • addEcommerceItem() Parameters:
    • Price
  • trackEcommerceOrder() Parameters:
    • grandTotal
    • subTotal
    • tax
    • shipping
    • discount

For example, all the following values are not valid currency variables:

  • “5.3$”
  • “EUR5.3”
  • “5,4”
  • “5.4”
  • “5.44”

The following values are valid currency variables:

  • 5
  • 5.3
  • 5.44

If your Ecommerce software provides the values as string only, you can call the Javascript function parseFloat() to convert the values into a valid format. First make sure the string you want to work with does not contain currency symbols or other characters, for example “554.30”. You can then pass that value through the function as shown:

parseFloat("554.30");

Note: The JavaScript function parseFloat() does not support comma separated decimal values “25,3” so you might also have to replace the commas with dots first.

Other JavaScript functions that you may find useful

The following options may be useful especially when your Ecommerce shop is a Single Page App:

  1. removeEcommerceItem(productSKU) – This removes a product from the order by SKU. You still need to call trackEcommerceCartUpdate to record the updated cart in Matomo.
  2. clearEcommerceCart() – This clears the order completely. You still need to call trackEcommerceCartUpdate to record the updated cart in Matomo.
  3. getEcommerceItems() – Returns all ecommerce items currently in the untracked ecommerce order. The returned array will be a copy, so changing it won’t affect the ecommerce order. To affect what gets tracked, use the methods: addEcommerceItem(), removeEcommerceItem(), clearEcommerceCart(). Useful to see the list of what will be tracked before you track an order or cart update.

See all available APIs in the Matomo Ecommerce Developer documentation for the JavaScript Tracking API.

And once you have your Ecommerce data logged in Matomo, you may also want to access all of the reporting data via the Matomo API: learn more about the Ecommerce Analytics Reporting API.

Previous FAQ: Analyse Ecommerce reporting to improve your sales