Ecommerce (GA4) Developer Guide

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:

1. Implement with the data layer (Recommended)
2. 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

Note: Each value included in a given data layer must also be captured in Google Tag Manager via a recommended event parameter and data layer variable. The examples below show how this must be done for the ecommerce items parameter and data layer variable, while additional parameters can be found in the GA4 event reference.

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.

Note: GA4 is compatible with the UA ecommerce schema, but the UA ecommerce schema is not compatible with the GA4 schema. If you have tagged your site for GA4 properties alongside UA, do not replace your older schemas with GA4 ecommerce data types.

Clearing the ecommerce object

It's recommended that you use the following command to clear the ecommerce object prior to pushing an ecommerce event to the data layer. Clearing the object will prevent multiple ecommerce events on a page from affecting each other.

dataLayer.push({ ecommerce: null });  // Clear the previous ecommerce object.

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({ ecommerce: null });  // Clear the previous ecommerce object.
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 onProductClick(productObj) {
  dataLayer.push({ ecommerce: null });  // Clear the previous ecommerce object.
  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({ ecommerce: null });  // Clear the previous ecommerce object.
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({ ecommerce: null });  // Clear the previous ecommerce object.
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({ ecommerce: null });  // Clear the previous ecommerce object.
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({ ecommerce: null });  // Clear the previous ecommerce object.
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({ ecommerce: null });  // Clear the previous ecommerce object.
  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({ ecommerce: null });  // Clear the previous ecommerce object.
  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({ ecommerce: null });  // Clear the previous ecommerce object.
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
• 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 - {{Ecommerce 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({ ecommerce: null });  // Clear the previous ecommerce object.
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({ ecommerce: null });  // Clear the previous ecommerce object.
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 getEcommerceData() {
  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