This document describes ecommerce event compatibility and translation between Universal Analytics (UA) and Google Analytics 4 (GA4).
Background
GA4 ecommerce events are automatically translated to equivalent UA events when sent to a UA property. Translation also occurs when sending UA ecommerce events to a GA4 property. This document explains how translation works, the compatibility of events and any trade-offs you might have to make when relying on automatic translation.
Purpose
Translation between UA and GA4 ecommerce events helps with the following:
- Ease of implementation: adopt GA4 ecommerce by using your existing UA implementation with a minor configuration update.
- Eliminate need to dual-tag: you can send the same ecommerce events to a UA and GA4 property. This provides an option to transition to GA4 and keep your UA ecommerce implementation, without requiring the maintenance of a dual-tag configuration.
Trade-offs
Compatibility provides flexibility to choose a GA4 migration path that's most appropriate to meet your short-term and long-term requirements of maintaining your UA implementation.
Most GA4 ecommerce events/parameters are compatible with UA and vice versa. For the small number of cases where incompatibilities exist, depending on the migration choice you make, either your UA or GA4 ecommerce reports may not be fully populated with data.
It's important you review each migration option for details on compatibility and the required configuration.
How translation works
GA4 Event Tag
- Using gtag is the recommended way to send GA4 ecommerce events. However, the GA4 Event tag can read ecommerce data pushed to the Data Layer.
- GA4 Event Parameters that are configured directly in a GA4 Event tag will take precedence over any gtag/Data Layer or custom variable provided data.
- The GA4 Event tag is backwards compatible with the ecommerce event data used
for Universal Analytics. The precedence behavior is as follows:
- Use GA4 ecommerce events.
- If GA4 ecommerce events are not found then look for and use UA ecommerce events.
- If a UA ecommerce event is used with a GA4 Event tag, the event will first be translated to the equivalent GA4 ecommerce event before it is sent to the GA4 property. This applies whether using gtag, Data Layer, or Custom Object.
Universal Analytics Tag
- The Universal Analytics tag supports reading GA4 ecommerce events (including data that is sent using gtag).
- If reading GA4 ecommerce events is enabled in the tag then the precedence
behavior is as follows:
- Use GA4 ecommerce events.
- If GA4 ecommerce events are not found then look for and use UA ecommerce events.
- If a GA4 ecommerce event is used with a Universal Analytics Tag, the event will first be translated to the equivalent UA ecommerce event before it is sent to the UA property. This applies whether using gtag, Data Layer, or Custom Object.
Comparable parameters for UA and GA4
The following table shows comparable ecommerce parameters for Universal Analytics and Google Analytics 4.
Universal Analytics parameter name | Google Analytics 4 parameter name | Notes |
---|---|---|
affiliation |
affiliation |
|
checkout_step |
||
checkout_option |
||
content_type |
||
coupon |
coupon |
|
currency |
currency |
When sending a UA event to a GA4 property, this currency value will be
used for the GA4 items[].currency parameter. |
location_id |
||
payment_type |
||
shipping |
shipping |
|
shipping_tier |
||
tax |
tax |
|
transaction_id |
transaction_id |
|
value |
value |
|
items[] |
items[] |
|
items[].name |
items[].item_name |
|
items[].id |
items[].item_id |
|
items[].affiliation |
||
items[].brand |
items[].item_brand |
|
items[].category |
items[].item_category items[].item_category2 items[].item_category3 items[].item_category4 items[].item_category5 |
The category of the item. Up to 5 levels of hierarchy can be specified.
See Category parameter translation
for details on how category translation is handled between UA and GA4
events.
|
items[].currency |
||
items[].coupon |
items[].coupon |
|
items[].discount |
||
items[].list_name |
items[].item_list_name |
|
items[].list_position |
items[].index |
|
items[].location_id |
||
items[].price |
items[].price |
|
items[].quantity |
items[].quantity |
|
items[].variant |
items[].item_variant |
|
promotions[] |
For GA4, items[] is used with promotion specific parameters
such as items[].promotion_id . |
|
promotions[].id |
items[].promotion_id |
These parameters do not get translated when sending a UA event to GA4 or vice versa. |
promotions[].name |
items[].promotion_name |
These parameters do not get translated when sending a UA event to GA4 or vice versa. |
promotions[].creative_name |
||
promotions[].creative_slot |
items[].creative_slot |
These parameters do not get translated when sending a UA event to GA4 or vice versa. |
Category parameter translation
Translation for the category parameter is handled as a special case when sending GA4 events to UA or vice versa.
For Universal Analytics, when setting the items[].category
parameter, you use
/
as a delimiter to specify up to five levels of hierarchy. In Google
Analytics 4, you use enumerated category parameters to specify up to five levels
of hierarchy: items[].item_category
, items[].item_category2
,
items[].item_category3
, items[].item_category4
, and
items[].item_category5
.
The behavior for category translation is as follows:
- For GA4 events translated to UA, enumerated categories will be combined into
a single
category
parameter, with each category delimited by/
. - For UA events translated to GA4, the value of the category parameter will be split to populate the corresponding GA4 enumerated categories.
- If you intend to send GA4 events to UA, it's recommended that you do not use
the
/
character in category values, since this will be interpreted as a category delimiter when translating to UA. - Only the first 5 category levels will be used, regardless of how many are defined.
Category translation example
The following examples show a UA category parameter translated to GA4. The same principle applies when translating a GA4 event to UA.
A UA event with a category that defines 5 levels of hierarchy:
gtag("event", "add_to_cart", {
items: [{
...
category: "Apparel/Adult/Shirts/Crew/Short sleeve",
...
}]
});
The UA event translated to a GA4 event, with enumerated categories:
gtag("event", "add_to_cart", {
items: [{
...
item_category: "Apparel",
item_category2: "Adult",
item_category3: "Shirts",
item_category4: "Crew",
item_category5: "Short sleeve",
...
}]
});
Compatibility between UA and GA4 events
The table below shows comparable ecommerce events for Universal Analytics and Google Analytics 4 and the translation behavior when sending a UA event to GA4 and vice versa.
For each row in the table, each column provides the following information:
- UA event and GA4 event columns indicate comparable events based on what they are intended to measure.
- Parameters lists parameters with no equivalent between the respective UA and GA4 events. GA4 only lists parameters that are only used with the GA4 event and UA only lists parameters that are only used with the UA event.
- Translation behavior (Sending UA to GA4) describes the translation behavior when sending a UA event to a GA4 property. The notes provide details on the data sent, differences from the GA4 event, and any notable effects on GA4 reports.
- Translation behavior (Sending GA4 to UA) describes the translation behavior when sending a UA event to a GA4 property. The notes provide details on the data sent, differences from the UA event, and any notable effects on UA reports.
UA event | GA4 event | Parameters | Translation behavior (Sending UA to GA4) |
Translation behavior (Sending GA4 to UA) |
---|---|---|---|---|
Product
Impressions (impressions )
|
|
GA4 only:
item_list_id item_list_name items[].affiliation items[].currency items[].discount items[].item_list_id items[].location_id |
Compatible.
All UA parameters are translated to GA4 equivalents and sent.
GA4 reports that require any GA4 only parameters will be incomplete.
|
Compatible.
GA4 parameters with an equivalent UA parameter are translated and sent. GA4 only parameters are not sent.
The event-level item_list_name parameter is ignored, only
the item-level item_list_name will be sent.
UA reports populated with data from the GA4 event will be complete / unchanged.
|
Product
Clicks (click )
|
|
GA4 only:
item_list_id item_list_name items[].affiliation items[].currency items[].discount items[].item_list_id items[].location_id UA only: content_type |
Not compatible. A select_content custom event and a content_type
custom parameter are sent. No items data is sent.
|
Not compatible. A UA event hit is sent with general as the event_category and
select_item as the event_action . No items
data is sent.
|
Promotion
Clicks (promoClick )
|
|
GA4 only:
creative_name creative_slot location_id promotion_id promotion_name items UA only: content_type promotions |
Not compatible. A select_content custom event is sent with
content_type and promotions as custom
parameters. The promotions custom parameter does not contain
any useful data.
|
Not compatible. A UA event hit is sent with general as the event_category and
select_promotion as the event_action . No
promotions data is sent.
|
Views of Product
Details (detail )
|
|
GA4 only:
currency value items[].affiliation items[].currency items[].discount items[].item_list_id items[].location_id |
Compatible.
All UA parameters are translated to GA4 equivalents and sent.
GA4 reports that require any GA4 only parameters will be incomplete.
|
Compatible.
GA4 parameters with an equivalent UA parameter are translated and sent. The exception is
item_list_name , which is not sent. Of the GA4 only
parameters, currency and value are sent with
the hit as
currency and
Transaction revenue, respectively. event_value
is also set to the value parameter, as an integer.
Note that the translation from GA4 to UA includes event_value , but this is normally not set for UA hits.
UA reports populated with data from the GA4 will mostly be complete / unchanged.
Item list name will be missing.
|
add_to_wishlist*
*
items data is not supported for UA.
|
|
GA4 only:
items[].affiliation items[].currency items[].discount items[].item_list_id items[].location_id |
Compatible.
All UA parameters are translated to GA4 equivalents and sent.
GA4 reports that require any GA4 only parameters will be incomplete.
|
Compatible.
An equivalent
event hit is sent with ecommerce as
event_category , add_to_wishlist as
event_action , and the value parameter
as event_value .
UA reports populated with data from the GA4 event will be complete / unchanged.
Since this event isn't generally supported in UA ecommerce reports, it won't have any remarkable effect.
|
Adding a Product to a
Shopping Cart (add )
|
|
GA4 only:
items[].affiliation items[].currency items[].discount items[].item_list_id items[].location_id |
Compatible.
All UA parameters are translated to GA4 equivalents and sent.
GA4 reports that require any GA4 only parameters will be incomplete.
|
Compatible.
GA4 parameters with an equivalent UA parameter are translated and sent.* GA4 only parameters are not sent.
* item_list_name is not sent but this behavior is
consistent with gtag.js (UA), which does not send
list_name .
UA reports populated with data from the GA4 event will be complete / unchanged.
|
Removing a Product
from a Shopping Cart (remove )
|
|
GA4 only:
items[].affiliation items[].currency items[].discount items[].item_list_id items[].location_id |
Compatible.
All UA parameters are translated to GA4 equivalents and sent.
GA4 reports that require any GA4 only parameters will be incomplete.
|
Compatible.
GA4 parameters with an equivalent UA parameter are translated and sent.* GA4 only parameters are not sent.
* item_list_name is not sent but this behavior is consistent
with gtag.js (UA), which does not send list_name .
UA reports populated with data from the GA4 event will be complete / unchanged.
|
N/A |
|
Event is only recommended for GA4. |
Not compatible*.
*It's unlikely your UA implementation sends this event since it is not
a recommended event. To ensure GA4 reports are complete, you can
implement this event for UA using the GA4 format.
If you implement the GA4 event for UA, it will show up as an
event
without
items data, which may not be very useful. It will
not affect UA ecommerce reporting.
|
Not compatible.
An event hit
is sent with general as event_category ,
view_cart as event_action , and the
value parameter as event_value .
items data is not sent.
Since this event isn't generally supported in UA ecommerce reports, it won't have any remarkable effect.
|
Checkout
Steps (checkout , checkout_option )
|
|
GA4 only:
items[].affiliation items[].currency items[].discount items[].item_list_id items[].location_id |
Compatible.
All UA parameters are translated to GA4 equivalents and sent.
GA4 reports that require any GA4 only parameters will be incomplete.
|
Compatible.
GA4 parameters with an equivalent UA parameter are translated and sent.* GA4 only parameters are not sent.
* item_list_name is not sent but this behavior is consistent
with gtag.js (UA), which does not send list_name .
begin_checkout is effectively equivalent to sending a
checkout_progress event with checkout_step
set to 1 .
UA reports populated with data from the GA4 event will be complete / unchanged.
|
add_payment_info
|
|
GA4 only:
currency value coupon payment_type items UA: N/A: Parameters are not supported.
|
Not compatible*.
*Since UA doesn't support parameters for this event, none are sent. It
will work but likely won't be very useful.
GA4 reports that require any event parameters will be incomplete.
|
Compatible.
An equivalent
event hit is sent with ecommerce as
event_category , add_to_wishlist as
event_action , and the value parameter
(casted to integer) as event_value . Note that the translation from GA4 to UA includes event_value , but this is normally not set for UA hits.
UA reports populated with data from the GA4 event will be complete / unchanged.
Since this event isn't generally supported in UA ecommerce reports, it won't have any remarkable effect.
|
N/A |
|
Event is only recommended for GA4. |
Not compatible*.
*It's unlikely your UA implementation sends this event since it is not
a recommended event. To ensure GA4 reports are complete, you can
implement this event for UA using the GA4 format.
If you implement the GA4 event for UA, it will show up as an
event
without
items data, which may not be very useful. It will
not affect UA ecommerce reporting.
|
Not compatible*.
An event hit
is sent with general as event_category ,
add_shipping_info as event_action , and the
value parameter (casted to integer) as
event_value . The GA4 currency parameter is
sent with the hit as
currency.
Since this event isn't generally supported in UA ecommerce reports, it won't have any remarkable effect.
|
Checkout
Steps (checkout , checkout_option )
|
N/A | Events are only recommended for UA. |
Event will be treated as a
custom event. Only event-level parameters will be sent, no
items data will be sent.
Since these events aren't generally supported in GA4 ecommerce reports,
they won't have any remarkable effect.
|
N/A |
Promotion
Impressions (promoView )
|
|
GA4 only:
creative_name creative_slot location_id promotion_id promotion_name items UA only: promotions |
Not compatible. A view_promotion custom event is sent with
promotions as custom parameter. The promotions
custom parameter does not contain any useful data.
|
Not compatible. A UA event hit is sent with engagement as the event_category and
view_promotion as the event_action . No
promotions data is sent. The event is marked as a
Non-Interaction event.
|
Measuring
Purchases (purchase )
|
|
GA4 only:
items[].affiliation items[].currency items[].discount items[].item_list_id items[].location_id |
Compatible.
All UA parameters are translated to GA4 equivalents and sent.
Event-level currency is used since item-level
currency is not supported.
GA4 reports that require any GA4 only parameters will be incomplete.
|
Compatible.
GA4 parameters with an equivalent UA parameter are translated and sent.* GA4 only parameters are not sent.
* item_list_name is not sent but this behavior is consistent
with gtag.js (UA), which does not send list_name .
UA reports populated with data from the GA4 event will be complete / unchanged.
|
Measuring
Refunds (refund )
|
|
GA4 only:
affiliation items[].affiliation items[].currency items[].discount items[].item_list_id items[].location_id |
Compatible.
All UA parameters are translated to GA4 equivalents and sent.
Event-level currency is used since item-level
currency is not supported.
GA4 reports that require any GA4 only parameters will be incomplete.
|
Compatible.
GA4 parameters with an equivalent UA parameter are translated and sent.* GA4 only parameters are not sent.
* item_list_name is not sent but this behavior is consistent
with gtag.js (UA), which does not send list_name .
UA reports populated with data from the GA4 event will be complete / unchanged.
|