How to Set Up GA4 Custom Dimensions on Magento 2 (and the Names That Break Events)

TL;DR

The extension gives you eight named dimension toggles, up to five product attributes and four user properties, spread across two configuration sections on two different tiers. Registering them in GA4 is a separate job with its own rules, and three of those rules will cost you two days each if you get them wrong: the string you type has to match what the extension sends, item-scoped dimensions are the scarcest kind Google gives you, and some names are refused outright. There is also one dated change that explains why a customer-group report may disagree with your order grid.

Key Takeaways

• The eight Custom Dimension - * toggles and the five additional product attributes ship in the base extension. The Measurement Protocol user properties and Track Only Specific Customer Groups are PRO [3].
• The admin labels and the strings GA4 needs are different strings. The guide is explicit: "use browser, browser_version, platform and customer_group in the User Property field" [3].
• Saving the configuration is not the last step on the Magento side. "After making any extension configuration changes, remember to re-generate the JSON and re-import and overwrite the existing GTM container" [3].
• The five product attributes describe products, so they ride in the items array and register as item-scoped dimensions, where a standard GA4 property allows 10 against 25 user-scoped and 50 event-scoped [1]. Five attributes is half that allowance.
• Two different mechanisms reject two different sets of names. GA4 refuses registration of its reserved parameter names [2]; since v1.17.2 (July 16, 2026) the extension skips a custom attribute named after a standard item field and logs which attribute to rename [3].
• Purchase events sent before v1.16.1 (March 6, 2026) can carry the session's customer group instead of the order's, on both the client and server paths [3].
• A mis-registered dimension costs 24 to 48 hours before data appears, and another 48 hours of waiting if you have to delete one to free quota [1].

The three groups of controls and where they live

Open WeltPixel → Google Analytics 4 Ecommerce → General Configuration and nine of the eleven controls below are on that screen. The other two live in the Measurement Protocol section, and which section a value comes from tells you which tier you need and which path it travels on.

The first nine rows ship in the base extension [3]. The last two belong to the Measurement Protocol section, which the guide heads "(PRO VERSION ONLY)" [3]. Send User Properties with enabled events attaches a User Properties object to each enabled Measurement Protocol event, described in the guide as "containing data that can be used to create Custom Dimensions" [3]. Whether any of these values should leave your store is a separate question, and the PII controls article answers it for customer ID and customer group specifically. Which tier you actually need, across every feature and not just this one, is settled in the STANDARD versus PRO comparison.

Why does the admin label differ from the string you type in GA4?

Because the admin shows you a human label and the payload carries a machine name, and nothing warns you when you register the wrong one.

The four selectable user properties appear in Magento as Browser / Browser Version / Platform (Operating System) / Customer Group [3]. The guide then tells you what to do in GA4: "When creating Custom Dimensions for the enabled User Properties, use browser, browser_version, platform and customer_group in the User Property field" [3]. Register "Browser Version" and you get a dimension that reports nothing, with no error anywhere to tell you why. Register browser_version and it fills.

This is the single cheapest mistake to avoid in the whole setup and the one most likely to be made, because the Magento screen is the last thing you looked at before switching tabs to GA4.

What happens between saving the toggle and seeing data?

Four things, in this order, and only the first one is in the Magento admin.

Save the configuration. Then regenerate and reimport the container, because the extension's own instruction is unambiguous: "After making any extension configuration changes, remember to re-generate the JSON and re-import and overwrite the existing GTM container to ensure your settings are picked up by Google" [3]. Skipping this is why a toggle you definitely switched on produces nothing. Then register the dimension in GA4 against the parameter or user property name the extension sends. Then wait: "After 24-48 hours, you can start to report on and advertise with the custom dimension or metric" [1].

What you may type at the registration step is constrained, and the constraint is published. GA4's reserved item parameter names cannot be used when creating custom dimensions, and that list includes item_brand, item_category through item_category5, item_id, item_list_id, item_list_name, item_name, item_variant, affiliation, currency, promotion_id and promotion_name, alongside the cid and session_id and user_id family; the reserved user property list adds first_open_time, session_number and relatives [2]. The prefix rules sit on the neighboring lists: event parameter names may not begin with _, firebase_, ga_, google_ or gtag., and user property names may not begin with the first four [2]. Those are the names a Magento product attribute tends to carry, because both vocabularies were built to describe the same catalog. Registering a custom dimension for a parameter GA4 already collects as a predefined dimension "will not affect cardinality, but it will use one of your custom dimension quota" [1], so a duplicate registration still consumes a slot.

One naming rule comes from our side, and both the legacy dataLayer article and the event verification guide already carry it: since v1.17.2 (July 16, 2026) the extension skips a custom attribute dimension named after a standard GA4 item field such as price or quantity, which GA4 populates itself and which appear on none of its reserved lists [2], and logs which attribute you need to rename [3]. An older fix belongs in the same audit: a dimension built on an attribute with a null value used to block the whole event, fixed in v1.12.9 (September 5, 2023) [3].

That verification guide also covers DebugView, the preview window and the server-side log chain, including Enable File Log, which writes Measurement Protocol traffic to var/log/ga4.log, and Enable Debug Collect, which posts to Google's debug endpoint [3].

Which five product attributes are worth a slot?

Count your property's spare item-scoped slots before you fill these in. The five additional custom attributes describe products, so they travel inside the items array, which puts them in item scope, and item scope is the tightest allowance Google gives a standard property:

Those are the current published limits [1]. Fill all five attribute slots and one Magento extension has taken half your store's item-scoped allowance, permanently as far as your reporting is concerned, because freeing a slot is not instant: "If you hit the limit for custom dimensions, you'll need to wait 48 hours after deleting dimensions to add new ones" [1]. Add the 24 to 48 hour reporting delay on the new one and a single wrong choice costs two days twice.

So nominate the five against a criterion. Item-scoped dimensions are meant for "custom data like item color or item size within the items array of an ecommerce event" [1], which is the shape of a merchandising attribute you plan to segment on. Google's explicit warnings are worth reading against your attribute list before you commit anything: avoid a unique ID per user, a session ID, or a timestamp as dimension values, all three named as high-cardinality mistakes [1]. A per-product attribute with thousands of distinct values is the same mistake wearing a product label.

The customer group in your history may be the wrong one

Customer Group is where this gets retroactive, and the boundary has a date on it.

From the changelog: v1.16.1 (March 6, 2026) "Fixed an issue that would prevent purchase events from sending the correct Customer Group value. Previously, the event would read from the session-level data, and has been updated to read from the order-level data, for both client-side and server-side implementations" [3]. Read that carefully. Purchase events from before that release can carry whatever group the session happened to hold rather than the group recorded on the order, on both paths, which means a wholesale-versus-retail revenue split spanning March 2026 is comparing two different measurements.

The dimension itself is older than the fix. Measurement Protocol user properties arrived in v1.14.1 (April 19, 2024), and Customer Group joined them as a user property in v1.14.9 (November 14, 2024) [3]. If your GA4 property predates either date, the absence of values in that window says the extension was not sending them yet.

FAQ

Does the extension create the custom dimensions in GA4 for me?

No. Magento decides what gets sent; GA4 decides what gets reported. You switch the toggles on in the extension, regenerate and reimport the container [3], then create a matching custom dimension in the GA4 admin. Neither side tells the other that a name is missing.

Why is my Browser Version dimension empty?

Almost certainly because the User Property field holds a label instead of a name. The guide specifies browser, browser_version, platform and customer_group [3]. There is no error state for this, only an empty column.

How many of the five product attributes should I actually use?

As few as you will segment on. A standard GA4 property allows 10 item-scoped custom dimensions in total [1], so five attributes from one extension is half the store's allowance, and reclaiming a slot means a 48 hour wait after deleting a dimension [1].

Are custom dimensions a PRO feature?

The eight toggles and the five product attributes are in the base feature set. The Measurement Protocol user properties and customer-group scoping are PRO [3].

Can I reuse a name GA4 already uses?

No, and the refusal comes from GA4 rather than from Magento. Reserved item parameter names such as item_name and item_variant cannot be used for custom dimensions, and on the event parameter side no name may begin with _, firebase_, ga_, google_ or gtag. [2].

The dimension toggles and product attributes are part of the Magento 2 Google Analytics 4 extension, with the Measurement Protocol user properties on its PRO tier, currently v1.17.5, released September 16, 2026.

Last detail, and it surprises people on their first report: "any value in a custom dimension that resembles a number will be treated as a number, even if it was originally formatted as text" [1]. A size attribute of 10, 12, 14 comes back as arithmetic.

Sources

1. [GA4] About custom dimensions and metrics, Google Analytics Help, retrieved September 21, 2026, https://support.google.com/analytics/answer/10075209
2. Event naming rules, Google Analytics Help, retrieved September 21, 2026, https://support.google.com/analytics/answer/13316687
3. WeltPixel Google Analytics 4 User Guide, v1.17.5, September 16, 2026, https://docs.weltpixel.com/GA4/User-Guide-WeltPixel-Google-Analytics-4.html