[GA4] Migrate ecommerce data collection from Universal Analytics

Best practices for setting up ecommerce data collection in Google Analytics 4 properties
This article is for website owners who want to collect ecommerce data in both their Universal Analytics and Google Analytics 4 properties. This article also provides some best practice information for mobile app owners who use Google Analytics for Firebase.
In this article, the term schema means "event and parameter names".

The structure and naming of the events and parameters has changed for Google Analytics 4 properties. While Google Analytics 4 properties will collect data from events and parameters of any name, you'll need to use specific names and parameters to get the most useful ecommerce reporting in your Google Analytics 4 property.

If you are upgrading to a Google Analytics 4 property from a Universal Analytics property, you should

  • Leave your Universal Analytics implementation unchanged 
  • Create duplicate events for your Google Analytics 4 property. Use the new event names and parameters that are required for Google Analytics properties. You will have two independent implementations side by side, each doing slightly different things.

While it's possible to use your existing Universal Analytics (ecommerce) event names and parameters for your Google Analytics 4 property, this is not advised.

Be cautious about sharing data across Universal Analytics and Google Analytics 4 ecommerce

While it's possible to use your existing Universal Analytics ecommerce implementation (dataLayer events and gtag.js code) with a Google Analytics 4 property, your Google Analytics 4 ecommerce reports will not be complete unless you  change your implementation to use the Google Analytics 4 event names and parameters. The gtag.js library does some, but not all of the event and parameter translation required. 

You cannot use the Google Analytics 4 event and parameter names for Universal Analytics because Universal Analytics will not collect any data for events that it doesn't recognize. For example, all Google Analytics 4 ecommerce events have the parameter item_id instead of id.  If you rely on ecommerce tagging in Universal Analytics, do not update your existing dataLayer or events to be in line with the new Google Analytics 4 schema. If there are new features you want to take advantage of in the Google Analytics 4 schema, you can add additional data to your dataLayer or additional events to capture data in the new schema.

Because of this, the best practice is to have two implementations in place: one for Universal Analytics and one for your Google Analytics 4 property. 

Since this will result in sending two events where you would ordinarily only send a single event, you can also decide to rely on your Universal Analytics implementation, adding only the additional events/ parameters required to send data to Google Analytics 4 properties. However, this requires a deep understanding of the two different schemas and how they compare, so be sure to keep the following in mind:

  • You can keep your Universal Analytics dataLayer structure and objects, but 
    • You'll need to add new Google Analytics 4 events/ parameters to access the full reporting capabilities in Google Analytics 4 properties. 
    • Where a Universal Analytics event has been deprecated in Google Analytics 4, we recommend creating a duplicate event with the updated Google Analytics 4 name 
  • Without updating the ecommerce schema, Google Analytics 4 properties will be able to collect event counts but may not be able to populate ecommerce reports due to missing required parameters such as item_id.

Getting started

To get started, you must add code to your site/app to collect ecommerce data. We’ll talk about the general structure of the ecommerce schema in Google Analytics 4 properties and then walk through more details of the implementation for Users using gtag.js or Google Tag Manager. 

There are two main aspects to building the ecommerce schema in Google Analytics 4 properties:

  • An event specifies how to interpret the product, list, and/ or promotion data that you send.
  • Parameters pass more specific information about an event. Parameters help you better understand business trends, such as the brand or category of the item, any coupons or discounts that were used or other important information. 
    • In Google Analytics 4 properties, one of the new changes to enable more processing and reporting flexibility is the introduction of an items array. Parameters are embedded in the items array (details). Note that this is different from the Universal Analytics dataLayer where additional action information was required to be specified for distinct events. 
    • Note that ecommerce tagging follows the same event/parameter limitations as the rest of Google Analytics 4: you can specify up to 25 custom parameters per event (the items array only takes up one slot) and up to 50 custom dimensions and 50 custom metrics per project (details).

Required parameters for Google Analytics 4 ecommerce

(required parameters in bold)

If you do not include the required parameters for ecommerce-specific events (items, item_id, item_name), these events will not show up in ecommerce reports in Google Analytics 4. Instead, they will be reported as ordinary custom events.  

 

Event name

Parameters

view_item

currency, items, value

view_item_list

items, item_list_name, item_list_id

select_item

items, item_list_name, item_list_id

add_to_wishlist

currency, items, value

add_to_cart

currency, items, value

view_promotion

items, promotion_id, promotion_name, creative_name, creative_slot, location_id

select_promotion

items, promotion_id, promotion_name, creative_name, creative_slot, location_id

view_cart

currency, items, value

remove_from_cart

currency, items, value

begin_checkout

coupon, currency, items, value

add_payment_info

coupon, currency, items, payment_type, value

add_shipping_info

coupon, currency, items, shipping_tier, value

purchase

affiliation, coupon, currency, items, transaction_id, shipping, tax, value

refund

affiliation, coupon, currency, items, transaction_id, shipping, tax, value
 

Note: Parameters (coupon, affiliation, item_list_name, item_list_id) could be passed either at the event or item level. If present at both event and item level then item level would win.

 

Event Parameter

Item-level Parameters

Items (see below)

affiliation, coupon, currency, discount, index, item_id, item_brand, item_category, item_category2, item_category3, item_category4, item_category5, item_list_name, item_list_id, item_name, item_variant, price, quantity
 

The following table describes the individual items array parameters that are available for collection.

 

Items array parameter name

Description

affiliation

The name or code of the affiliate (partner/vendor; if any) associated with an individual item

coupon

The coupon name/code (if any) associated with an individual item

discount

The discount (if any) associated with an individual item

item_brand

The brand of the item

item_category

The category of the item

item_category2

The second category hierarchy or additional taxonomy for the item

item_category3

The third category hierarchy or additional taxonomy for the item

item_category4

The fourth category hierarchy or additional taxonomy for the item

item_category5

The fifth category hierarchy or additional taxonomy for the item

item_id

The id of the item (required)

item_name

The name of the item (required)

item_variant

The item variant or unique code or description for additional item details/options

price 

The price of the item

quantity 

The quantity of the item being interacted with

Mapping the ecommerce schemas across Universal Analytics and Google Analytics 4 properties

  • Generally, you’ll be mapping event and parameter names between two schemas. Here is the full list of event and  parameter names in Universal Analytics and the event reference in Google Analytics 4, as well as a mapping between the two in the table below.
    • Note that some names have changed, for example, the data layer parameters that used to be “impression” or “product” are now consolidated into “items”. 
    • An items array has been introduced to enable you to better log details associated with each item.
There is no distinction between ecommerce and enhanced ecommerce in Google Analytics 4 properties.

Tabular summary of the schema changes from Universal Analytics to Google Analytics 4 properties

How to use this table:

  • Compare the event changes (column A vs column C)
  • Review the dimension/ parameter requirements and changes (column B vs column D). Note the additional table below that highlights the changes in parameters for items/ products
  • If you have an app with Firebase,  note the following changes to event names and make the corresponding changes to match Google Analytics 4 event names (column C). Any new ecommerce-specific reporting in Google Analytics 4 properties will not appear in the Firebase interface.  Additionally, the Firebase version of detailed event reports, for ecommerce_purchase and purchase for instance, may not be updated.
    • Changed
      • ecommerce_purchase (Google Analytics for Firebase)  -> purchase
      • ecommerce_refund (Google Analytics for Firebase) -> refund
      • select_content (Google Analytics for Firebase) -> select_item
      • present_offer (Google Analytics for Firebase) -> select_promotion
    • New
      • view_cart
 

Column A

Universal Analytics event names (reference)

Column B

Universal Analytics dimensions (reference)

Column C

Google Analytics 4 event names (reference)

Column D

Google Analytics 4 parameters (reference)

purchase

refund

id

coupon

revenue

tax

shipping

currencyCode

**products (see detail below)

purchase

refund

transaction_id

coupon

value

tax

shipping

currency

**items (see detail below)

checkout_option

option

*add_payment_info

payment_type

checkout_option

revenue

currencyCode

option

*add_shipping_info

price

currency

shipping_tier

checkout

currencyCode

revenue

coupon

step (analytics.js only)

option (analytics.js only)

**products

*begin_checkout

currency

value

coupon

**items

addToCart

N/A

removeFromCart

N/A 

currencyCode

revenue

**products 

*add_to_cart

*add_to_wishlist

*remove_from_cart

*view_cart

currency

value

**items 

pageview

currencyCode

**products

revenue

*View_item (default for views)

currency 

**items

value

pageview

productClick 

list

N/A - did not exist

**products 

*View_item_list (merchandising view)

*select_item

item_list_name

item_list_id

**items 

pageview

promotionClick

id

name

creative

position 

**products

*view_promotion

*select_promotion

promotion_id

promotion_name

creative_name

creative_slot

**items
 

*New or changed event name from Universal Analytics

 

Detail

Google Analytics 4 parameters

Corresponding Universal Analytics dimensions

**Items/Products detail

items 

item_id

item_name

item_brand

item_category

item_category2

item_category3

item_category4

item_category5

item_variant

affiliation

discount

coupon

price

quantity

products

id

name

brand

category

N/A - did not exist

N/A - did not exist

N/A - did not exist

N/A - did not exist

variant

N/A - did not exist

N/A - did not exist

coupon

price

quantity

gtag.js implementations

We recommend that you have two implementations in place: one full implementation for Universal Analytics and one full implementation for your Google Analytics 4 property.

  • Leave your Universal Analytics implementation alone and create duplicate events for Google Analytics 4 with updated names aligned with the Google Analytics 4 schema. You will have two independent implementations side by side doing slightly different things.
  • If you rely on the Universal Analytics schema (i.e. do not make changes to events), you will not see ecommerce reporting in your Google Analytics 4 property for event names that have changed (be sure to reference the above table for more details on the event name changes). 
    • gtag.js implementations have the option to re-use existing Universal Analytics ecommerce event instrumentations for Google Analytics 4 by using Connected Site Tags or adding an additional Config line to the gtag.js snippet on page. In order to smooth out the transition from Universal Analytics to the Google Analytics 4 ecommerce schema, gtag.js has added functionality to partially translate classic ecommerce event parameters to the Google Analytics 4 schema. 
    • Note that there are net new events that exist only in Google Analytics 4 properties. These will not be captured if you rely on the Universal Analytics schema and may result in incomplete funnels once reporting is rolled out. 
    • Ecommerce items in an event will only count as one parameter for the purposes of parameter limit enforcement.
  • The following event names in Universal Analytics will automatically be considered ecommerce events in Google Analytics 4 properties:
    • purchase
    • refund
    • begin_checkout
    • add_to_cart
    • remove_from_cart
    • view_cart
    • add_to_wishlist
    • view_item*
    • view_promotion
    • select_promotion
    • select_item*
    • view_item_list
    • add_payment_info
    • add_shipping_info
    • * These events support only a single item.
  • When one of the above events is sent to a Google Analytics 4 property via the gtag.js API, Google Analytics 4 ecommerce event processing will look for an items key in the event model.  If found, the parameter will be parsed as an array of up to 200 items, where each item is an object with a predefined schema. For each item, Google Analytics 4 ecommerce will transmit data in any field from a predefined list. The following will be the initial predefined fields for an item:
    • item_id
    • item_name
    • item_brand
    • item_category
    • item_category2
    • item_category3
    • item_category4
    • item_category5
    • item_variant
    • price
    • quantity
    • coupon
    • index
    • item_list_name
    • item_list_id
    • discount
    • affiliation
    • location_id
    • promotion_id (event or item level; item takes precedence)
    • promotion_name (event or item level; item takes precedence)
    • creative_name (event or item level; item takes precedence)
    • creative_slot (event or item level; item takes precedence)
  • If you don't update your event instrumentation from Universal Analytics, you will no longer see the following events in your Google Analytics 4 ecommerce reports, because the old event names won't be recognized. Create a duplicate event for your Google Analytics 4 property with an updated name that is aligned with the Google Analytics 4 schema.
    • set_checkout_option (this is merged with begin_checkout in Google Analytics 4)
    • checkout_progress (this is merged with begin_checkout in Google Analytics 4)
    • select_content (this is no longer a Google Analytics 4 ecommerce event, but still a recommended event, without support for items array)
  • Be cautious about using your Universal Analytics ecommerce event instrumentation for your Google Analytics 4 property because:
    • 1) Some Universal Analytics ecommerce event names are deprecated or have changed. If you don't update these outdated event names, you might end up losing the items params of these events in your Google Analytics 4 reports (as regular custom events won't have items array support). You may also see missing steps in ecommerce funnel reports if the funnel includes an event that is a new Google Analytics 4 event.
    • 2) Google Analytics 4 properties introduce additional item-level parameters, eg. affiliation, currency, and a few item_category parameters. You will not get the benefits of these additional parameters if you don't retag. However, these additional parameters are optional and won't break if you don't use them.
  • Using connected site tags will collect all events hardcoded for Universal Analytics. This will not enable full ecommerce reporting in your Google Analytics 4 property. 

Updating the dataLayer for Google Tag Manager

To take advantage of new events introduced for Google Analytics 4 properties, you'll need to add new events/ parameters in the dataLayer and also need to add new event triggers in Google Tag Manager. 

  • You will have the choice to manually determine which datalayer key to map to a specified event parameter. 
    • For example, in Universal Analytics you must push "id" (of the purchase event) in the dataLayer object as "ecommerce.purchase.actionField.id". With Google Analytics 4, you can specify the dataLayer key to map to the "transaction_id" event parameter. If you re-used the UA dataLayer object, you can create a Google Tag Manager dataLayer variable mapped to the key "ecommerce.purchase.actionField.id" and assign it to the Google Analytics 4 event as "transaction_id". Or, you can map the Google Tag Manager datalayer variable to the key "ecommerce.purchase.transaction_id", and assign it to the event parameter "transaction_id". 
  • You have the option to continue to reference existing dataLayer objects
    • If you leverage existing dataLayer objects from your Universal Analytics implementation, you cannot take advantage of the new Google Analytics 4 schema (e.g., additional item level params). But, you will get some ecommerce reporting for existing events if you manually create the necessary variables in Tag Manager. 
When configuring an Google Analytics 4 Event tag in Google Tag Manager to send an ecommerce event using the dataLayer, you have to manually enter dataLayer variables as event parameters, such as param name: ‘items’ and value {{ecommerce.purchase.products}}, where {{ecommerce.purchase.products}} is a Tag Manager dataLayer variable that needs to be created to read the products array from the dataLayer. You need to create a dataLayer variable for each event-level parameter and assign it to an event parameter, and then repeat for each ecommerce event. See the example below for details.
 

Universal Analytics Google Tag Manager dataLayer push code (reference)

GA4 Google Tag Manager implementation re-using existing dataLayer implemented for Universal Analytics

dataLayer.push({

  'ecommerce': {

    'purchase': {

      'actionField': {

        'id': 'T12345',                         // Transaction ID. Required for purchases and refunds.

        'affiliation': 'Online Store',

        'revenue': '35.43',                     // Total transaction value (incl. tax and shipping)

        'tax':'4.90',

        'shipping': '5.99',

        'coupon': 'SUMMER_SALE'

      },

      'products': [{                            // List of productFieldObjects.

        'name': 'Triblend Android T-Shirt',     // Name or ID is required.

        'id': '12345',

        'price': '15.25',

        'brand': 'Google',

        'category': 'Apparel',

        'variant': 'Gray',

        'quantity': 1,

        'coupon': ''                            // Optional fields may be omitted or set to empty string.

       },

       {

        'name': 'Donut Friday Scented T-Shirt',

        'id': '67890',

        'price': '33.75',

        'brand': 'Google',

        'category': 'Apparel',

        'variant': 'Black',

        'quantity': 1

       }]

    }

  }

});

 

You need to create datalayer variables for each event-level parameter, like this below. 

 

You need to repeat this for each ecommerce event you track. 

Implementation examples

Refer to the events/ parameters table for more specifics. 

Setting up the purchase funnel

Typically there are four key steps to the purchase funnel:

View products

  • User views an item or a list of items. To measure item list views/impressions, push a list of items to the dataLayer and collect an event along with that data. 
    • gtag.js 
      • Event: view_item_list OR view_item
        • In Universal Analytics, the equivalent event is “impressions”
      • Parameters: must include at least item_id OR item_name
        • In Universal Analytics, parameters did not have the prefix “item_”; “list_position” is now “index’
    • Google Tag Manager - 
      • Event: view_item_list OR view_item
        • In Universal Analytics, the equivalent event is “impressions” 
      • Parameters: items is a data layer variable “ecommerce.items”; The parameters are “items{ }” and must include at least item_id OR item_name
        • In Universal Analytics, parameters did not have the prefix “item_”; “position” is now “index’

Add to cart

  • User selects an item and add that to their cart; variations of this could be adding to a wishlist or sending a request more information
    • gtag.js
      • Event: add_to_cart
      • Parameters: must include at least item_id OR item_name
    • Google Tag Manager
      • Event: add_to_cart
        • In Universal Analytics, the equivalent dataLayer event is “addToCart” and this required an additional actionFieldObject “add”; actionFieldObject is no longer required in the dataLayer object for Google Analytics 4.
      • Parameters: as part of “items”, must include at least item_id OR item_name
        • In Universal Analytics this required the separate variable “products” for product info

Checkout

  • User goes to their cart with an item and begins the checkout process; there are additional steps such as adding payment or shipping information, which have their own distinct events in the Google Analytics 4 ecommerce schema. If your checkout flow includes these additional steps, be sure to send specific events for them to be included in your purchase funnel.  
    • gtag.js
      • Event: begin_checkout
        • In Universal Analytics, there are also events for ‘checkout_progress” and “set_checkout_option” which are not available in Google Analytics 4 properties, instead, see specific events for add_to_cart, add_shipping_info, and add_payment_info. 
      • Parameters: must include at least item_id OR item_name
    • Google Tag Manager
      • Event: begin_checkout
        • In Universal Analytics, the equivalent dataLayer event is “checkout” and this required an additional actionFieldObject “checkout”. This actionField is not needed in Google Analytics 4, however you shouldn’t change your existing implementation, otherwise you will break ecommerce in Universal Analytics. 
      • Parameters: as part of “items”, must include at least item_id OR item_name

        • In Universal Analytics this required the separate variable “products” for product info

Purchase

  • Measuring the checkout process 
    • In Google Analytics 4 properties, this event is automatically marked as a conversion once it has been added to your code
    • gtag.js
      • Event: purchase
        • In Universal Analytics, there are also events for ‘checkout_progress” and “set_checkout_option” which are not yet available in Google Analytics 4 properties 
      • Parameters: must include at least transaction_id
 

Universal Analytics - analytics.js

reference

Universal Analytics - gtag.js

reference

Google Analytics 4 Properties - gtag.js

reference

ga('ec:addProduct', {

  'id': 'P12345',

  'name': 'Android Warhol T-Shirt',

  “Other optional values”

});

 

ga('ec:setAction', 'purchase', {

  'id': 'T12345', 

  “Other optional values”                        });

gtag('event', 'purchase', {

  "transaction_id": "123",

  “Other optional values”

  "items": [

    {

      "id": "P12345",

      "name": "Android Warhol T-Shirt",

     “Other optional values”

    },

    {

      "id": "P67890",

      "name": "Flame challenge TShirt",

     “Other optional values”

    }

  ]

});

gtag('event', 'purchase', {

  "transaction_id": "123",

  “Other optional values”

  "items": [

    {

      "item_id": "P12345",

      "item_name": "Android Warhol T-Shirt",

     “Other optional values”

    },

    {

      "item_id": "P67890",

      "item_name": "Flame challenge TShirt",

     “Other optional values”

    }

  ]

});

analytics.js uses enhanced ecommerce to set a productFieldObject to specify product details as well as an actionFieldObject to specify the action occurring.

 

The migration to gtag.js introduces fundamental differences. There is only one event that is automatically logged as ecommerce; both the transaction and product information can be included; product information can be sent in an array (as opposed to requiring additional events). 

Send a purchase event with the items in the transaction. 

 

The naming for required values is different, such as “id” moving to “item_id” and “name” moving to “item_name.”

 

There are also differences in optional values that should be observed. 

Send a purchase event with the items in the transaction
 
  • Google Tag Manager
    • Event: purchase
      • In Universal Analytics, the equivalent event data layer event is “purchase”; requires an action field for the full transaction 
    • Parameters: as part of “items”, must include at least item_id OR item_name
      • In Universal Analytics this required the separate variable “products” for product info
 

Universal Analytics - Tag Manager

reference

Google Analytics 4 Properties - gtag.js

reference

dataLayer.push({

  'ecommerce': {

    'purchase': {

      'actionField': {

        'id': 'T12345',

        ‘Other optional values’

      },

      'products': [{

        'name': 'Triblend Android T-Shirt',     

        'id': '12345',

        ‘Other optional values’

       },

       {

        'name': 'Donut Friday Scented T-Shirt',

        'id': '67890',

        ‘Other optional values’

       }]

    }

  }

});

dataLayer.push({

  'event': 'purchase',

  'ecommerce': {

    'items': [{

      'item_name': 'Triblend Android T-Shirt',

      'item_id': '12345',

      ‘Other optional values’

    },

    {

      'item_name': 'Donut Friday Scented T-Shirt',

      'item_id': '67890',

      ‘Other optional values’

 

    }]

  }

});

Push your transaction details into the dataLayer using the purchase action, along with an event that will fire an enhanced ecommerce-enabled tag.

Send transaction data with a pageview if available when the page loads. Otherwise, use an event when the transaction data becomes available.

 

Notable Changes:

  • Schema now lists items rather than products; while Google Analytics 4 properties can read the legacy schema, this will only collect basic information like event counts and will prevent additional capabilities (eg funnel reporting).
  • The naming for required values is different, such as “id” moving to “item_id” and “name” moving to “item_name.”
    • There are also differences in optional values that should be observed.

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:

Additional activities

Most ecommerce engagements include more than the standard four steps mentioned above. Ecommerce in Google Analytics 4 properties enables you to capture more information on other important activities such as 

  • Highlight an incentive that was associated with an item or event
    • Coupon enables you to specify the name of any coupon associated with an item (eg free shipping, or 20% one item); data type is string and this is an item parameter 
    • Discount (new) enables you to specify the monetary value of the discount associated with an item (eg “0.05”); data type is float 
  • Promotion - these include on-site messaging to direct a user to a specific section of your site/ app
    • Requires a promotion_id or promotion_name, otherwise, data will only be available in the standard events table reports
  • Refunds - measure a refund of a transaction
    • Refund is a specific event that can handle full or partial refunds
    • Requires a transaction_id, otherwise, data will only be available in the standard events table reports 
Was this helpful?
How can we improve it?