Repository markdown
Source: docs/data-layer/EVENTS.md
Data Layer Events Reference
Complete list of all events pushed to window.dataLayer by the application, grouped by category.
Routing
virtual_page_view
Fired on every page navigation (both initial load and client-side). Always the first custom event on each page.
| Property | Type | Description |
|---|---|---|
event | string | "virtual_page_view" |
page.url | string | Full URL including query string |
page.path | string | Pathname only (no origin or query) |
page.referrer | string | Previous page URL (internal) or external referrer on new entry |
page.title | string | Document title at time of push |
Trigger logic: Inline script on initial load; RoutingCompleteTracker on client-side route changes.
Consent
consent: default (gtag command)
Pushed as the very first dataLayer entry, before virtual_page_view. Sets the baseline consent state.
["consent", "default", { "ad_storage": "denied", "analytics_storage": "denied", ... }]consent: update (gtag command)
Pushed when the user interacts with the consent banner.
["consent", "update", { "ad_storage": "granted", "analytics_storage": "granted", ... }]cookie_update
Custom event fired alongside consent: update for GTM trigger use.
| Property | Type | Description |
|---|---|---|
event | string | "cookie_update" |
consent_status | string | "accepted" or "denied" |
consent_mode | string | "update" |
consents | object | Full consent state object |
Ecommerce (GA4)
All ecommerce events follow the GA4 recommended event schema. They are gated behind virtual_page_view — guaranteed to never fire before the routing event on any page.
Each ecommerce push is preceded by { ecommerce: null } to clear the previous ecommerce object (GA4 requirement).
view_item_list
User views a list/collection of products.
| Property | Type | Description |
|---|---|---|
event | string | "view_item_list" |
ecommerce.item_list_id | string | Unique list identifier |
ecommerce.item_list_name | string | Display name of the list |
ecommerce.items | Ga4Item[] | Array of product items |
select_item
User clicks/selects a product from a list.
| Property | Type | Description |
|---|---|---|
event | string | "select_item" |
ecommerce.item_list_id | string | List the item was selected from |
ecommerce.item_list_name | string | Display name of that list |
ecommerce.items | Ga4Item[] | The selected item(s) |
view_item
User views a product detail page.
| Property | Type | Description |
|---|---|---|
event | string | "view_item" |
ecommerce.currency | string | ISO 4217 currency code |
ecommerce.value | number | Total value of items viewed |
ecommerce.items | Ga4Item[] | The viewed item(s) |
add_to_cart
User adds item(s) to the cart.
| Property | Type | Description |
|---|---|---|
event | string | "add_to_cart" |
ecommerce.currency | string | ISO 4217 currency code |
ecommerce.value | number | Total value of added items |
ecommerce.items | Ga4Item[] | Added item(s) |
remove_from_cart
User removes item(s) from the cart.
| Property | Type | Description |
|---|---|---|
event | string | "remove_from_cart" |
ecommerce.currency | string | ISO 4217 currency code |
ecommerce.value | number | Total value of removed items |
ecommerce.items | Ga4Item[] | Removed item(s) |
view_cart
User views the cart page/drawer.
| Property | Type | Description |
|---|---|---|
event | string | "view_cart" |
ecommerce.currency | string | ISO 4217 currency code |
ecommerce.value | number | Total cart value |
ecommerce.items | Ga4Item[] | All items in cart |
begin_checkout
User initiates the checkout process.
| Property | Type | Description |
|---|---|---|
event | string | "begin_checkout" |
ecommerce.currency | string | ISO 4217 currency code |
ecommerce.value | number | Checkout value |
ecommerce.coupon | string | Applied coupon code (empty string if none) |
ecommerce.items | Ga4Item[] | Items in checkout |
add_shipping_info
User selects a shipping method.
| Property | Type | Description |
|---|---|---|
event | string | "add_shipping_info" |
ecommerce.currency | string | ISO 4217 currency code |
ecommerce.value | number | Order value |
ecommerce.coupon | string | Applied coupon code |
ecommerce.shipping_tier | string | Selected shipping method name |
ecommerce.items | Ga4Item[] | Items in order |
add_payment_info
User selects/enters payment information.
| Property | Type | Description |
|---|---|---|
event | string | "add_payment_info" |
ecommerce.currency | string | ISO 4217 currency code |
ecommerce.value | number | Order value |
ecommerce.coupon | string | Applied coupon code |
ecommerce.payment_type | string | Payment method name |
ecommerce.items | Ga4Item[] | Items in order |
purchase
Order is completed/confirmed.
| Property | Type | Description |
|---|---|---|
event | string | "purchase" |
ecommerce.transaction_id | string | Unique order/transaction ID |
ecommerce.affiliation | string | Store name |
ecommerce.value | number | Total order value |
ecommerce.tax | number | Tax amount |
ecommerce.shipping | number | Shipping cost |
ecommerce.currency | string | ISO 4217 currency code |
ecommerce.coupon | string | Applied coupon code |
ecommerce.items | Ga4Item[] | Purchased items |
refund
An order (or part of an order) is refunded.
| Property | Type | Description |
|---|---|---|
event | string | "refund" |
ecommerce.transaction_id | string | Original transaction ID |
ecommerce.value | number | Refund amount |
ecommerce.currency | string | ISO 4217 currency code |
ecommerce.items | Ga4Item[] | Refunded items |
add_to_wishlist
User adds item(s) to a wishlist.
| Property | Type | Description |
|---|---|---|
event | string | "add_to_wishlist" |
ecommerce.currency | string | ISO 4217 currency code |
ecommerce.value | number | Total value of wishlisted items |
ecommerce.items | Ga4Item[] | Wishlisted item(s) |
view_promotion
User views a promotional banner/element.
| Property | Type | Description |
|---|---|---|
event | string | "view_promotion" |
ecommerce.promotion_id | string | Promotion identifier |
ecommerce.promotion_name | string | Promotion display name |
ecommerce.creative_name | string? | Creative asset name |
ecommerce.creative_slot | string? | Slot/placement identifier |
ecommerce.location_id | string? | Location on page |
select_promotion
User clicks/interacts with a promotion.
| Property | Type | Description |
|---|---|---|
event | string | "select_promotion" |
ecommerce.promotion_id | string | Promotion identifier |
ecommerce.promotion_name | string | Promotion display name |
ecommerce.creative_name | string? | Creative asset name |
ecommerce.creative_slot | string? | Slot/placement identifier |
ecommerce.location_id | string? | Location on page |
Search
search
User performs a search.
| Property | Type | Description |
|---|---|---|
event | string | "search" |
search_term | string | The search query |
result_count | number | Number of results returned |
Ga4Item Schema
All ecommerce events include an items array. Each item follows this schema:
| Property | Type | Required | Description |
|---|---|---|---|
item_id | string | Yes | Product SKU |
item_name | string | Yes | Localized product name |
affiliation | string | No | Store/seller name |
coupon | string | No | Item-level coupon |
discount | number | No | Discount amount per unit |
index | number | No | Position in list (0-based) |
item_brand | string | No | Brand name |
item_category | string | No | Primary category |
item_list_id | string | No | ID of the list this item appeared in |
item_list_name | string | No | Name of that list |
item_variant | string | No | Variant (color, size, etc.) |
price | number | Yes | Unit price in the specified currency |
quantity | number | Yes | Number of units |
GTM Internal Events
These are pushed by GTM itself (not by application code), but appear in the dataLayer:
| Event | Source |
|---|---|
gtm.js | GTM container initialization |
gtm.dom | DOM ready |
gtm.load | Window load complete |