New e-commerce guides/references

Hey Piwik Pro team,

Version 17.2.0 just released and improved on the e-commerce module but I can’t seem to find any documentation related to this. Particularly the “Product detail view”.

Is there any updated documentation or reference materials anywhere?


Hi alexanderf!

The 17.2.0 has not been released in the product yet. The updated documentation should be available a day after the release.

You can check the current product version in the menu section of Piwik PRO:


1 Like

After having read the documentation on the new e-commerce methods in v. 17.2, I am still a bit confused on how the new ecommerceCartUpdate() method should be used.

The ecommerceCartUpdate() method tracks the initial state of the cart. It should be called each time a session starts and only once per session. Its purpose is to restore the state of a cart that was abandoned in a previous session.

What if the cart is empty, should we still call this function with no products when the session starts?

If we call this function with no products, will this not be treated as Shopping stage = Abandoned cart?

What if the user is initially logged out, should we call this function immediately after the user logs in?

Thank you for your clarifications.

Hi joao!

I can see that there are parts of the documentation that could be misleading without additional context. We will most likely update it soon :slight_smile:.

If the cart is empty there is no need to send the ecommerceCartUpdate. I’d even advise against using it that way (see 2nd answer).

The cart will be treated as an abandoned cart.

For scenarios where shop cart is populated after user logs in I would send ecommerceCartUpdate immidiately after the user logs in. If user logs in and the cart stays empty then you should not send an empty ecommerceCartUpdate.

1 Like


Isn’t the event “ecommerceCartUpdate” supposed to be sent once per session?

If so, the documentation says it should be used “once per page”, which is misleading:

Thank you!

I agree, the way Piwik PRO manages cart updates and abandoned carts is very confusing.

The official documentation says :

Tracking a cart update has two steps:

But now that the Ecommerce cart update tag has been released with version 18.2, it says that we can’t use it with the Ecommerce add to cart or the Ecommerce remove from cart tags, because it conflicts with them?! :face_with_raised_eyebrow:

How exactly are we supposed to be using the new Ecommerce cart-related tags then?

Hi @joao!

It’s best to check and use this guide when it comes to ecommerce tracking.

It is true that the cart update and add to cart or remove from cart methods should not be used together. Sorry for the inconvenience - we’ll update the documentation as it contains some outdated info.

Hi @anthonybartczak , thank you for the documentation link. While the documentation clearly explains how to create these 3 cart-related tags, it doesn’t really explain when we should be using the Ecommerce cart update over the other 2 tags.

Am I correct in assuming that the way these tags should be used is as follows:

  • We should trigger the Ecommerce add to cart and Ecommerce remove from cart tags whenever a user adds products to a cart or remove products from a cart, respectively. The products array sent with these tags should only contain the products and quantities added/removed for that event (similar to GA4 add_to_cart and remove_from_cart events).
  • Or, we should trigger the Ecommerce cart update tag each time the cart is updated, and in this case the products array should include all products and quantities contained in the cart after the update (similar to a GA4 view_cart event).

Is this correct? Thank you.

@joao add to cart and remove from cart should be used instead of the cart update tag (or method) where it’s possible because it provides some additional data you can use in the Analytics module:

  • Adds to cart
  • Removes from cart
  • Cart-to-detail rate (combined with product detail views)

This approach simply allows for a more detailed ecommerce interaction analysis (e.g. creating user flow reports based on add to cart or remove from cart events).

Some ecommerce sites don’t have these events implemented (add to cart, remove from cart) and therefore using ecommerceCartUpdate() each time the cart content changes might be the proper solution in their case.

I wouldn’t compare ecommerceCartUpdate() to GA4 view_cart as the Piwik PRO one is not an event that you can use in Analytics - its only purpose is to update the Piwik PRO cart so it contains the visitor’s current cart content. It doesn’t indicate that the visitor has viewed the cart content.

1 Like

@anthonybartczak This is good know, thank you so much. :pray:

Maybe I didn’t read the documentation carefully enough, but I don’t remember seeing anywhere that the recommended method is to use the add to cart and remove from cart events, like you just said. This is actually what I am currently using, but only because I didn’t really understand how the cart update tag should be used! :joy:

No problem at all. Perhaps the article/documentation could be worded better. I’ll note this down :wink:.

@anthonybartczak My fault, this is already pretty clear in the current documentation page, it appears that the page was substantially updated since the last time I read it a couple of months ago :smiley: :

We recommend using scenario 1B, where you track when users add items to their cart and when they remove items from it. This scenario lets you collect metrics such as Adds to cart, Removes from cart and Cart-to-detail rate; use the add-to-cart and remove-from-cart events as funnel steps and; analyze how users interact with the cart in the user flow report.

If you can’t track the add-to-cart and remove-from-cart events separately, you can use scenario 1A, which tracks updates to the cart. But it’s better to use scenario 1B when you can.

Maybe it would be helpful to have a “last updated date” information somewhere on your documentation pages, as currently it’s a bit hard to know if something was changed recently.