Usage

Events and where they fire

Event	When	Main parameters
view_item_list	Category pages, search results, brand (feature) pages, vendor stores (Multi-Vendor). Again after AJAX pagination, sorting, view switching and filters.	item_list_id (category_<id>, search_results, feature_<variant_id>, vendor_<id>), item_list_name, items with index
select_item	Click on a product link (or the quick view button) in a tracked list	item_list_id, item_list_name, items[1]
view_item	Product page and quick view. Carries the list of the preceding select_item.	currency, value, items[1]
add_to_cart	Any cart increase: product page, lists, quick view, wishlist, quantity increase in the cart (AJAX or not)	currency, value, items (added quantity)
remove_from_cart	Removal from the cart or mini-cart, quantity decrease, clearing the cart	currency, value, items (removed quantity)
view_cart	Cart page	currency, value, coupon, items
begin_checkout	Checkout page (full page load)	currency, value, coupon, items
add_shipping_info	The shopper changes the shipping method on checkout. If the preselected method is kept, the event is sent when the order is placed.	shipping_tier, items
add_payment_info	The shopper changes the payment method. If the preselected method is kept, the event is sent when the order is placed.	payment_type, items
purchase	Order landing page, once per order. In Multi-Vendor, one per vendor order.	transaction_id, value, tax, shipping, currency, coupon, affiliation, items
refund	Server-side, when an order enters a refund status	transaction_id, value, currency
search	Search results page (first page)	search_term
login	Successful storefront login	method (email or the social provider)
sign_up	Customer registration	method
add_to_wishlist	Product added to the wishlist	currency, value, items

Item parameters

Parameter	Source
item_id	Product code (SKU) or product ID (setting). For order lines, the code of the ordered option combination.
item_name	Product name in the configured language
affiliation	Multi-Vendor: vendor (company) name
item_brand	Value of the brand feature
item_category … item_category5	Path of the product’s main category, from the root down
item_variant	Variation features (Product variations add-on) and selected options, e.g. Color: White, Size: Large
price	Unit price after catalog promotions, in the reporting currency
discount	Unit discount from catalog promotions
quantity	Quantity
index, item_list_id, item_list_name	List context (lists, select_item, view_item)

Gifts added by promotions (free products) and child items of product bundles are not reported as cart changes.

AJAX add to cart

The add-on does not hook buttons. On the server it compares the cart at the start and at the end of each request and queues the matching events. They are delivered by:

• the AJAX response of the request itself (key kv_ga4 in the CS-Cart JSON response, sent on ce.ajaxdone). This covers add to cart without a page reload, the mini-cart and cart updates;
• the next rendered page, if the request ended with a redirect.

So any button, block or add-on that changes the cart through CS-Cart is tracked. Logins, logouts and order placement also change the cart, but they are not reported as cart events.

Google Tag Manager setup

In GTM mode the add-on pushes, for every ecommerce event:

dataLayer.push({ ecommerce: null });
dataLayer.push({
  event: 'add_to_cart',
  ecommerce: { currency: 'USD', value: 130, items: [ { item_id: 'H0148VPS1T', item_name: '…', price: 130, quantity: 1 } ] }
});

Events without items are pushed flat: {event: 'search', search_term: 'sony'}, {event: 'login', method: 'email'}.

A minimal container:

1. Google tag with your measurement ID, trigger Initialization – All Pages.
2. A GA4 Event tag:
   • Event name: {{Event}};
   • More settings → Ecommerce → Send Ecommerce data from the Data Layer;
   • Trigger: Custom Event with the regex view_item_list|select_item|view_item|add_to_cart|remove_from_cart|view_cart|begin_checkout|add_shipping_info|add_payment_info|purchase|add_to_wishlist.
3. A GA4 Event tag for search|login|sign_up, with the event parameters search_term and method read from Data Layer Variables.

The add-on writes the consent defaults with gtag('consent', 'default', …) before the container loads. Consent updates from the cookie dialog are pushed as gtag('consent', 'update', …), which GTM’s built-in consent checks understand.

Consent

• With the GDPR add-on (Settings → Cookie consent set to implicit or explicit): the dialog lists Google Analytics 4 and Google advertising. Accepting or declining them updates analytics_storage and the three ad signals (ad_storage, ad_user_data, ad_personalization). The choice is also remembered in the cookie kv_ga4_consent, so the next page starts with the right state.

• With another consent banner: call the add-on’s API from the banner’s callbacks:

  window.kvGa4.consent({ analytics: true, ads: false });

  or send your own gtag('consent', 'update', …). In Basic mode the tag loads only after kvGa4.consent({analytics: true}).

Purchases, de-duplication and the server-side fallback

1. When an order is placed on the storefront, the add-on stores the GA client ID (from the _ga cookie), the GA session ID and the consent state.
2. On the order landing page (checkout.complete), the purchase is printed once. A reload, the order link in an email or a second visit never sends it again.
3. When the Google tag has processed the purchase (gtag event_callback / GTM eventCallback), the page tells the server, which marks the order as confirmed.
4. Orders that are not confirmed after the configured delay are sent through the Measurement Protocol with the same transaction_id, client ID and session ID, and with the original order time. This covers ad blockers, closed tabs and payment pages that never return to the store. Orders are not sent when:
   • analytics consent was denied;
   • consent is unknown and the default for the customer’s billing country is denied;
   • the order failed, was declined or was canceled;
   • payment is still incomplete (status N: the server retries until the 72-hour window closes).
5. Refunds use the same client ID when it is known.

Rarely, both the browser and the server report an order, for example when the confirmation request failed after the tag had fired. The server uses the visitor’s own client ID and the same transaction_id, so GA4’s de-duplication of purchases with the same transaction ID for the same user applies.

Multi-Vendor

• One purchase per vendor order (child order), with affiliation = vendor name. The parent order is never sent.
• Refunds are sent per vendor order.
• Item affiliation is the vendor name on every event.
• Vendor store pages (companies.products) send view_item_list with item_list_id = vendor_<company_id>.

CS-Cart (Ultimate) storefronts

All settings can differ per storefront (another measurement ID, container or currency). Orders, refunds and the fallback use the settings of the storefront where the order was placed. The purchase affiliation is the storefront’s company name.