[UA→GA4] Migrate ecommerce data collection from UA to GA4

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.

The names of some ecommerce events and parameters have changed for Google Analytics 4 properties. Using the correct GA4 names and parameters will give you the most useful ecommerce reporting and ecommerce event data in your GA4 property.

To migrate from UA to GA4, you should

Leave your UA implementation unchanged
Create duplicate events for your GA4 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.

Avoid sharing ecommerce implementations across UA and GA4

If you use your existing UA ecommerce implementation (i.e. dataLayer events and gtag.js code) with a GA4 property, your GA4 ecommerce reports will not be complete. The gtag.js library automatically translates some, but not all of the UA event and parameters to what is needed for GA4.

On the other hand, you should not simply switch to the GA4 event and parameter names either. UA will not collect any data for events that it doesn't recognize. For example, all GA4 ecommerce events have the parameter item_id instead of id.

Because of this, the best practice is to have two implementations in place: one for UA and one for your GA4 property.

Since this will result in sending two events where you would ordinarily only send a single event, you may decide to rely on your UA implementation, and add only the additional events/ parameters required to send data to GA4 properties. However, this requires a deep understanding of the two different sets of events and parameters. If you keep your UA dataLayer structure and objects,

You'll need to add new GA4 events/ parameters to access the full reporting capabilities in GA4 properties
Where a UA event has been deprecated in GA4, you should create a duplicate event with the updated GA4 name

Basics: events and parameters

An event specifies how to interpret the product, list, and/or promotion data that you send. Parameters pass more specific information about an event.

For GA4, parameters are embedded in an items array (details). Note that this is different from the UA dataLayer where additional action information was required to be specified for distinct events.
Ecommerce tagging is subject to GA4 event and parameter limitations. 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 GA4 ecommerce

(required parameters in bold)

If you do not include the required parameters for ecommerce-specific events (e.g. items, item_id, item_name), these events will not show up in your GA4 ecommerce reports. Instead, they will be reported as 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

Parameters (coupon, affiliation, item_list_name, item_list_id) can be passed either at the event or item level. If present at both event and item level, item level takes precedence.

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 across UA and GA4

Some names have changed, for example, the data layer parameters that used to be “impression” or “product” are now consolidated into items.

There is now an items array.

There is no distinction between ecommerce and enhanced ecommerce in GA4 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 GA4 event names (column C). Any new ecommerce-specific reporting in GA4 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

UA event names (reference)

Column B

UA dimensions (reference)

Column C

GA4 event names (reference)

Column D

GA4 parameters (reference)

purchase

refund

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

name

creative

position

**products

*view_promotion

*select_promotion

promotion_id

promotion_name

creative_name

creative_slot

**items

*New or changed event name from UA

Detail

GA4 parameters

Corresponding UA 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

name

brand

Updating the dataLayer for Google Tag Manager

To take advantage of new events introduced for GA4 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 UA you must push "id" (of the purchase event) in the dataLayer object as "ecommerce.purchase.actionField.id". With GA4, 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 GA4 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 UA implementation, you cannot take advantage of the new GA4 event names and parameters (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 GA4 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.

UA Google Tag Manager dataLayer push code (reference)

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

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

Setting up the purchase funnel

There are typically four steps in a 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 UA, the equivalent event is “impressions”
- Parameters: must include at least item_id OR item_name
  - In UA, parameters did not have the prefix “item_”; “list_position” is now “index’
Google Tag Manager
- Event: view_item_list OR view_item
  - In UA, 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 UA, parameters did not have the prefix “item_”; “position” is now “index’

Add to cart

User selects an item and adds it to their cart. Variations of this could include adding to a wishlist or sending a request for 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 UA, the equivalent dataLayer event is “addToCart” and this required an additional actionFieldObject “add”; actionFieldObject is no longer required in the dataLayer object for GA4.
- Parameters: as part of “items”, must include at least item_id OR item_name
  - In UA, this required the separate variable “products” for product info

Checkout

User goes to their cart with an item and begins the checkout process. Additional steps such as adding payment or shipping information have their own GA4 events. If your checkout flow includes these additional steps, be sure to send specific events for them so that they can be included in your purchase funnel.

gtag.js
- Event: begin_checkout
  - In UA, there are also events for ‘checkout_progress” and “set_checkout_option” which are not available in GA4 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 UA, the equivalent dataLayer event is “checkout” and this required an additional actionFieldObject “checkout”. This actionField is not needed in GA4, however you shouldn’t change your existing implementation, otherwise you will break ecommerce in UA.
- Parameters: as part of “items”, must include at least item_id OR item_name
  - In UA this required the separate variable “products” for product info

Purchase

User makes a purchase

In GA4 properties, this event is automatically marked as a conversion once it has been added to your code
gtag.js
- Event: purchase
  - In UA, there are also events for ‘checkout_progress” and “set_checkout_option” which are not yet available in GA4 properties
- Parameters: must include at least transaction_id

UA - analytics.js

reference

UA - gtag.js

reference

GA4 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 UA, 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 UA this required the separate variable “products” for product info

UA - Tag Manager

reference

GA4 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:

GA4 lists items rather than products. While you can use your UA implementation, your GA4 property will only collect basic information like event counts and will not accomodate additional capabilities (e.g. 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 ecommerce activities

GA4 properties can capture additional information as well:

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?