This guide describes how to implement Google Analytics 4 (GA4) ecommerce features using Google Tag Manager on a website.
GA4 ecommerce enables product list, impression, promotion, and sales data to be sent with a number of suggested Ecommerce events.
You have two options to enable ecommerce in the tag editor screen of the web interface:
- Implement with the data layer (Recommended)
- Implement with a Custom JavaScript Variable
These sections will show you how to use the data layer to measure the listed ecommerce activities:
- Product/Item List Views/Impressions
- Product/Item List Clicks
- Product/Item Detail Views
- Adds/Removes from Cart
- Promotion Views/Impressions
- Promotion Clicks
- Checkouts
- Purchases
- Refunds
Migration from legacy ecommerce data layer objects
For those who have previously implemented
enhanced ecommerce for Google Analytics web properties and have data layer
objects like 'impressions'
and 'products'
, you may continue to use those in
place of references to 'items'
as shown in this document.
Measure product/item list views/impressions
To measure item list views/impressions, push a list of items to the data layer
and collect a view_item_list
event along with that data. This example assumes
that the details about the products displayed on a page are known when the page
loads:
// Measure product views / impressions
dataLayer.push({
'event': 'view_item_list',
'ecommerce': {
'items': [
{
'item_name': 'Triblend Android T-Shirt', // Name or ID is required.
'item_id': '12345',
'price': '15.25',
'item_brand': 'Google',
'item_category': 'Apparel',
'item_category2': 'Mens',
'item_category3': 'Shirts',
'item_category4': 'Tshirts',
'item_variant': 'Gray',
'item_list_name': 'Search Results',
'item_list_id': 'SR123',
'index': 1,
'quantity': '1'
},
{
'item_name': 'Donut Friday Scented T-Shirt',
'item_id': '67890',
'price': '33.75',
'item_brand': 'Google',
'item_category': 'Apparel',
'item_category2': 'Mens',
'item_category3': 'Shirts',
'item_category4': 'Tshirts',
'item_variant': 'Black',
'item_list_name': 'Search Results',
'item_list_id': 'SR123',
'index': 2,
'quantity': '1'
}]
}
});
Tag configuration for this example:
- Tag type: GA4 Event
- Event Name:
view_item_list
- Event Parameter (name - value): 'items' - {{Ecommerce Items}}
- Variable Type: data layer Variable - 'ecommerce.items'
- Trigger: event equals gtm.dom
Measure product/item list clicks
To measure clicks on product / item lists, push an item to the data layer and
collect a select_item
event to represent the clicked product, as in this
example:
/**
* Call this function when a user clicks on a product link.
* @param {Object} productObj An object that represents the product that is clicked.
*/
function(productObj) {
dataLayer.push({
'event': 'select_item',
'ecommerce': {
'items': [{
'item_name': productObj.name, // Name or ID is required.
'item_id': productObj.id,
'item_brand': productObj.brand,
'item_category': productObj.category,
'item_category2': productObj.category_2,
'item_category3': productObj.category_3,
'item_category4': productObj.category_4,
'item_variant': productObj.variant,
'item_list_name': productObj.list_name,
'item_list_id': productObj.list_id,
'index': productObj.index,
'quantity': productObj.quantity,
'price': productObj.price
}]
}
});
}
Tag configuration for this example:
- Tag type: GA4 Event
- Event Name:
select_item
- Event Parameter (name - value): 'items' - {{Ecommerce Items}}
- Variable Type: data layer Variable - 'ecommerce.items'
- Trigger: event equals select_item
Measure views/impressions of product/item details
To measure a view of product details, push a list of items to the data layer and
collect a view_item
event along with that data. This example assumes details
about the products displayed on a page are known at the time the page loads:
// Measure a view of product details. This example assumes the detail view occurs on pageload,
dataLayer.push({
'event': 'view_item',
'ecommerce': {
'items': [{
'item_name': 'Donut Friday Scented T-Shirt', // Name or ID is required.
'item_id': '67890',
'price': '33.75',
'item_brand': 'Google',
'item_category': 'Apparel',
'item_category2': 'Mens',
'item_category3': 'Shirts',
'item_category4': 'Tshirts',
'item_variant': 'Black',
'item_list_name': 'Search Results', // If associated with a list selection.
'item_list_id': 'SR123', // If associated with a list selection.
'index': 1, // If associated with a list selection.
'quantity': '1'
}]
}
});
Tag configuration for this example:
- Tag type: GA4 Event
- Event Name:
view_item
- Event Parameter (name - value): 'items' - {{Ecommerce Items}}
- Variable Type: data layer Variable - 'ecommerce.items'
- Trigger: event equals gtm.dom
Measure additions or removals from a shopping cart
Similarly, to measure additions or removals from a shopping cart, you can
collect an add_to_cart
or remove_from_cart
event along with the items that
are added or removed:
Add a product to a shopping cart
// Measure when a product is added to a shopping cart
dataLayer.push({
'event': 'add_to_cart',
'ecommerce': {
'items': [{
'item_name': 'Donut Friday Scented T-Shirt', // Name or ID is required.
'item_id': '67890',
'price': '33.75',
'item_brand': 'Google',
'item_category': 'Apparel',
'item_category2': 'Mens',
'item_category3': 'Shirts',
'item_category4': 'Tshirts',
'item_variant': 'Black',
'item_list_name': 'Search Results',
'item_list_id': 'SR123',
'index': 1,
'quantity': '2'
}]
}
});
Tag configuration for this example:
- Tag type: GA4 Event
- Event Name:
add_to_cart
- Event Parameter (name - value): 'items' - {{Ecommerce Items}}
- Variable Type: data layer Variable - 'ecommerce.items'
- Trigger: event equals add_to_cart
Remove a product from a shopping cart
// Measure the removal of a product from a shopping cart.
dataLayer.push({
'event': 'remove_from_cart',
'ecommerce': {
'items': [{
'item_name': 'Donut Friday Scented T-Shirt', // Name or ID is required.
'item_id': '67890',
'price': '33.75',
'item_brand': 'Google',
'item_category': 'Apparel',
'item_variant': 'Black',
'item_list_name': 'Search Results', // If associated with a list selection.
'item_list_id': 'SR123', // If associated with a list selection.
'index': 1, // If associated with a list selection.
'quantity': '1'
}]
}
});
Tag configuration for this example:
- Tag type: GA4 Event
- Event Name:
remove_from_cart
- Event Parameter (name - value): 'items' - {{Ecommerce Items}}
- Variable Type: data layer Variable - 'ecommerce.items'
- Trigger: event equals remove_from_cart
Measure promotions
You can measure both impressions and clicks on internal site promotions, such as banners displayed on the site itself advertising a sale on a particular subset of products, or an offer for free shipping.
Measure promotion views/impressions
To measure a view of product details, push promotion details to the data layer
and collect a view_promotion
event along with that data. This example assumes
details about the products displayed on a page are known at the time the page
loads:
// Measure promotion views. This example assumes that information about the
// promotions displayed is available when the page loads.
dataLayer.push({
'event': 'view_promotion',
'ecommerce': {
'items': [{
'item_name': 'Donut Friday Scented T-Shirt', // Name or ID is required.
'item_id': '67890',
'price': '33.75',
'item_brand': 'Google',
'item_category': 'Apparel',
'item_category2': 'Mens',
'item_category3': 'Shirts',
'item_category4': 'Tshirts',
'item_variant': 'Black',
'promotion_id': 'abc123',
'promotion_name': 'summer_promo',
'creative_name': 'instore_suummer',
'creative_slot': '1',
'location_id': 'hero_banner',
'index': 1,
'quantity': '1'
}]
}
});
Tag configuration for this example:
- Tag type: GA4 Event
- Event Name:
view_promotion
- Event Parameter (name - value): 'items' - {{Ecommerce Items}}
- Variable Type: data layer Variable - 'ecommerce.items'
- Trigger: event equals gtm.dom
Measure promotion clicks
To measure a click on a promotion, collect a select_promotion
event along with
an array of item the promotion is associated with:
/**
* Call this function when a user clicks on a promotion.
* @param {Object} promoObj An object that represents an internal site promotion.
*/
function onPromoClick(promoObj) {
dataLayer.push({
'event': 'select_promotion',
'ecommerce': {
'items': [{
'item_name': promoObj.name, // Name or ID is required.
'item_id': promoObj.id,
'item_brand': promoObj.brand,
'item_category': promoObj.category,
'item_category2': productObj.category_2,
'item_category3': productObj.category_3,
'item_category4': productObj.category_4,
'item_variant': promoObj.variant,
'promotion_id': promoObj.pid,
'promotion_name': promoObj.pname,
'creative_name': promoObj.pcreative_name,
'creative_slot': promoObj.pcreative_slot,
'location_id': promoObj.plocation,
'index': promoObj.index,
'quantity': promoObj.quantity,
'price': promoObj.price
}]
}
});
}
Tag configuration for this example:
- Tag type: GA4 Event
- Event Name:
select_promotion
- Event Parameter (name - value): 'items' - {{Ecommerce Items}}
- Variable Type: data layer Variable - 'ecommerce.items'
- Trigger: event equals select_promotion
Measure a checkout
To measure a checkout, push product details to the data layer and collect a
begin_checkout
event along with that data:
/**
* A function to handle a click on a checkout button.
*/
function onCheckout() {
dataLayer.push({
'event': 'begin_checkout',
'ecommerce': {
'items': [{
'item_name': 'Donut Friday Scented T-Shirt', // Name or ID is required.
'item_id': '67890',
'price': '33.75',
'item_brand': 'Google',
'item_category': 'Apparel',
'item_category2': 'Mens',
'item_category3': 'Shirts',
'item_category4': 'Tshirts',
'item_variant': 'Black',
'item_list_name': 'Search Results',
'item_list_id': 'SR123',
'index': 1,
'quantity': '1'
}]
}
});
}
Tag configuration for this example:
- Tag type: GA4 Event
- Event Name:
begin_checkout
- Event Parameter (name - value): 'items' - {{Ecommerce Items}}
- Variable Type: data layer Variable - 'ecommerce.items'
- Trigger: event equals begin_checkout
Measure purchases
To measure transactions, push a list of items to the data layer and collect a
purchase
event along with that data. This example assumes details about the
products displayed on a page are known at the time the page loads:
dataLayer.push({
'event': 'purchase',
'ecommerce': {
'transaction_id': 'T12345',
'affiliation': 'Online Store',
'value': '59.89',
'tax': '4.90',
'shipping': '5.99',
'currency': 'EUR',
'coupon': 'SUMMER_SALE',
'items': [{
'item_name': 'Triblend Android T-Shirt',
'item_id': '12345',
'price': '15.25',
'item_brand': 'Google',
'item_category': 'Apparel',
'item_variant': 'Gray',
'quantity': 1
}, {
'item_name': 'Donut Friday Scented T-Shirt',
'item_id': '67890',
'price': '33.75',
'item_brand': 'Google',
'item_category': 'Apparel',
'item_variant': 'Black',
'quantity': 1
}]
}
});
Tag configuration for this example:
- Tag type: GA4 Event
- Event Name:
purchase
- Data Layer Variables (Name - Data Layer Variable Name) :
- Ecommerce Items -
ecommerce.items
- Ecommerce Transaction ID -
ecommerce.transaction_id
- Ecommerce Affiliation -
ecommerce.affiliation
- Ecommerce Value -
ecommerce.value
- Ecommerce Tax -
ecommerce.tax
- Ecommerce Shipping -
ecommerce.shipping
- Ecommerce Currency -
ecommerce.currency
- Ecommerce Coupon -
ecommerce.coupon
- Ecommerce Items -
- Event Parameters (Parameter Name - Value):
- items - {{Ecommerce Items}}
- transaction_id - {{Ecommerce Transaction ID}}
- affiliation - {{Ecommerce Affiliation}}
- value - {{Ecommerce Value}}
- tax - {{Ecommerce Tax}}
- shipping - {{Ecommerce Shipping}}
- currency - {{commerce Currency}}
- coupon- {{Ecommerce Coupon}}
- Trigger: event equals purchase
Measure refunds
To measure a full refund of a transaction, collect a refund
event along with
the transaction ID of the transaction to be refunded:
// To refund an entire transaction, provide the transaction ID.
// This example assumes the details of the completed refund are
// available when the page loads:
dataLayer.push({
'event': 'refund',
'ecommerce': {
'transaction_id': 'T12345' // Transaction ID. Required for purchases and refunds.
}
});
Tag configuration for this example:
- Tag type: GA4 Event
- Event Name:
refund
- Event Parameter (name - value): 'items' - {{Ecommerce Items}}
- Variable Type: data layer Variable - 'ecommerce.items'
- Trigger: event equals gtm.dom
To measure a partial refund, add a list of items
that includes the IDs and
quantities to be refunded:
// To measure a partial refund, provide an array of productFieldObjects and
// specify the ID and quantity of each product to be returned. This example
// assumes the partial refund details are known at the time the page loads:
dataLayer.push({
'event': 'refund',
'ecommerce': {
'transaction_id': 'T12345', // Transaction ID.
'items': [{
'item_name': 'Donut Friday Scented T-Shirt',
'item_id': '67890', // ID is required.
'price': '33.75',
'item_brand': 'Google',
'item_category': 'Apparel',
'item_category2': 'Mens',
'item_category3': 'Shirts',
'item_category4': 'Tshirts',
'item_variant': 'Black',
'item_list_name': 'Search Results', // If associated with a list selection.
'item_list_id': 'SR123', // If associated with a list selection.
'index': 1, // If associated with a list selection.
'quantity': '1' // Quantity is required.
}]
}
});
Tag configuration for this example:
- Tag type: GA4 Event
- Event Name:
refund
- Event Parameter (name - value): 'items' - {{Ecommerce Items}}
- Variable Type: data layer Variable - 'ecommerce.items'
- Trigger: event equals gtm.dom
Use a Custom JavaScript Variable
If your website does not support a data layer, you can use a Custom JavaScript Variable to call a function that returns the ecommerce data object. This object should use the data layer syntax shown earlier in this guide, for example:
// A Custom JavaScript Variable that returns an ecommerceData object
// that follows the data layer syntax.
function() {
var ecommerceProductData = [
{
'item_name': 'Donut Friday Scented T-Shirt',
'item_id': '67890', // ID is required.
// Rest of the product data should follow the data layer syntax.
},
// Multiple products may be included.
];
return ecommerceProductData;
}
If you choose to use the Custom JavaScript Variable instead then you can use it in the same manner as you would the data layer - you can supply the value from the 'items' parameter as an event parameter in your tag configuration.
Tag configuration for this example:
- Tag type: GA4 Event
- Event Name: any
- Read data from Variable: {{gaEcommerceData}}
- Trigger: event equals gtm.dom
gaEcommerceData Variable Settings
- Variable type: Custom JavaScript
- Function body: Use the above example