Ecommerce event compatibility and translation reference (gtag.js)

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

• When a GA4 ecommerce event is sent to a UA property, the event is translated to the equivalent UA (gtag.js) ecommerce event.
  • UA event parameters are populated with values from comparable GA4 parameters. If a UA parameter cannot be populated from a GA4 event (i.e. there is no comparable parameter) then the parameter will be omitted when the event is sent to the UA property.
• When a UA (gtag.js) ecommerce event is sent to a GA4 property, the event is translated to the equivalent GA4 ecommerce event.
  • GA4 event parameters are populated with values from comparable UA parameters. If a GA4 parameter cannot be populated from a UA event (i.e. there is no equivalent parameter) then the parameter will be omitted when the event is sent to the GA4 property. In some cases, if a UA parameter does not have a comparable GA4 parameter, the parameter will be sent with the GA4 event as a custom parameter.
• All translations from GA4 to UA and vice versa are carried out client-side.
• Event/parameter translations are enabled by default, no user configuration is required and it cannot be disabled.

Comparable parameters for UA and GA4

The following table shows comparable ecommerce parameters for Universal Analytics and Google Analytics 4.

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.