Analytics
GA4 item-scoped custom dimensions for store catalogues
GA4 item-scoped custom dimensions are how I turn a catalogue attribute that already lives in Magento, Shopify or WooCommerce into a cut that merchandisers can use next to Items purchased. I am a Gold Coast web developer with 18 years on those three platforms. In 2026 the recommended ecommerce events are stable. The gap is the extra product facts that never make it into the items array.
Google already gives you item_id, item_name, item_brand, item_category through item_category5, and item_variant. That is enough for a tidy demo shop. It is not enough when a jeweller wants metal and stone, a sleepwear brand wants fabric and fit, or a Magento retailer wants range and stock state on the same SKU story as the Shopping feed. Those fields are item-scoped parameters. They only become report dimensions after you register them.
If purchase revenue is still fiction, fix that first. Use my notes on GA4 ecommerce events that match real revenue and on GA4 key events for ecommerce. This note assumes purchase already fires once with a real transaction_id.
Why GA4 item-scoped custom dimensions matter on a live catalogue
GA4 item-scoped custom dimensions matter on a live catalogue because merchandisers do not buy "Item name". They buy colourways, metals, lengths, and whether the hero SKU was in stock when someone added it.
Adobe Commerce treats product attributes as the building blocks of the catalogue: attribute sets, layered navigation, promotions, and configurable variations. WooCommerce does the same split with global attributes on variable products versus product-only custom fields. Shopify now lets a metafield definition become analytics queryable in ShopifyQL. None of that automatically lands in GA4.
I keep seeing the same meeting. Someone opens Ecommerce purchases, groups by Item name, and asks why yellow outsells black. The theme already has a colour swatch. The feed already has a colour column. GA4 has item_variant set to a hyphenated soup like yellow / s on one event and Yellow on the next. Or colour never left the PDP JavaScript. The report then looks like a different catalogue from the one operations run.
On retail conversion at scale Magento work treated funnels as operational tools. Without range or stock on the item, we were guessing which attribute set needed a PDP pass. On Their Nibs fabric and fit sit on the sleepwear PDP. On Tamannaah Fine Jewellery metal and collection are the catalogue language. item_category as "Rings" does not answer gold versus silver.
Shopify Analytics can group sales by a metafield when analyticsQueryable is on. That helps inside Shopify. It does not feed GA4 Explorations or Ads, and it does not help a property that also runs Magento. I still send the parameter on the GA4 items array.
How GA4 item-scoped custom dimensions actually work
GA4 item-scoped custom dimensions actually work as a two-step contract: you send a custom key on each object in the items array, then you register that key as a dimension with Item scope.
Google's item-scoped custom parameters guide is the implementation page I keep open. You may send up to 27 custom parameters on an item. A standard property can register 10 of those as item-scoped custom dimensions. Analytics 360 can register 25. The extra unregistered parameters are useful as a staging pool. They do not appear as dimensions until you create the definition.
The official example adds in_stock: true beside the prescribed fields on a tee. That is the pattern. The key lives on the item, not on the event. If you put in_stock next to transaction_id on purchase, you have an event-scoped parameter. It will not break down Items purchased the way an item-scoped dimension does.
About custom dimensions and metrics is the quota table. User-scoped, event-scoped and item-scoped each have their own cap. Do not burn an event-scoped slot on metal. Do not burn an item-scoped slot on payment type. Create item-scoped custom dimensions is the Admin path: Data display, Custom definitions, scope Item, parameter name exactly as tagged. Dimension name can have spaces. The parameter name cannot. Hyphens are not allowed in the dimension name. Scope and parameter name cannot change after save.
Google's ecommerce collection guide allows up to 200 items and says to set every ecommerce parameter you have. I treat that as fill the prescribed fields first. item_id is still the SKU you share with the warehouse and the Shopping feed. Recommended events already list brand, five category slots, variant, list id, price and quantity. If colour is a clean item_variant, I do not also send color. If variant is a mashed yellow / s string, I split colour out. Google's Admin example registers color when variant is doing other work.
Cardinality is the quiet limit. A unique engraving or serial explodes into (other). I want a closed list: in_stock and out_of_stock, 14k and 18k, cotton and silk. Booleans work in Google's sample. I still prefer string labels so two tags do not report true and 1.
The payload has to match on view_item_list, select_item, view_item, add_to_cart and purchase. If metal is PDP-only, Items viewed look complete and Items purchased look empty. Apps often send a parent ID on view and a variant ID on purchase. I overwrite the thank-you if I cannot fix the app. GTM should read ecommerce.items from a dataLayer the theme owns. Visual tagging cannot see a metafield. I still print the JSON on staging.
Production checklist for GA4 item-scoped custom dimensions
A store is ready to use GA4 item-scoped custom dimensions when a test SKU shows the same custom keys in DebugView on view, cart and purchase, and those keys exist as Item-scoped definitions.
- Write the attribute dictionary. Five facts merchandising will actually filter. On Magento that is an EAV or attribute-set field, not a one-product customizable option. On WooCommerce prefer a global attribute. On Shopify pick metafields the theme or feed already trusts.
- Map each fact to a parameter name: letters, numbers, underscore, start with a letter.
metal,fabric,in_stock,range. Notitem-metal. - Confirm it is not a prescribed field. Do not register
item_brandas a custom dimension. - Add the key to every item object you already send. Same type and casing.
Goldandgoldare two rows. - Keep list payloads honest. Forty-eight cards can send 48 items. Infinite scroll should fire another
view_item_listfor new rows, still withindex. - Fire a staging order. In DebugView open
purchase, expand items, and read the custom keys. If they are missing, stop. Registration will not invent them. - In Admin, create the item-scoped custom dimension. Editor or Administrator. Scope Item. Parameter name exact. Save once.
- Wait for a day of production traffic. Custom dimensions do not backfill the week before you registered them.
- Build one Exploration with Items purchased, not the event-scoped Purchases metric. Google's ecommerce metrics note says those scopes do not mix cleanly.
- Compare a known SKU to admin. If gold rings sold 12 units and the dimension shows 4, you are dropping the parameter on wallet checkout or a second purchase tag.
Do not register all 27 parameters. Pick the ones you will defend in a merchandising meeting.
What breaks when the items array is almost right
Almost-right items arrays break item reports in ways that look like catalogue problems.
The classic miss is scope. A developer adds metal on the event because GTM made it easy. DebugView shows metal. Explorations that use Item metal stay (not set). The fix is not another dimension. The fix is moving the key into each item.
The second miss is a second vocabulary. Theme pixel sends in_stock. App pixel sends stock_status. You register one. Half the catalogue looks empty. Inventory the owners the same way I inventory purchase tags: one writer for the items array.
Parent versus variant IDs still wreck this. view_item on a configurable Magento PDP sends the parent. purchase sends the simple SKU. Custom attributes that only exist on the simple never attach to the view. Collection work then looks like nobody saw gold, only bought it. Send the selected simple as soon as the shopper picks it.
High cardinality looks like success in week one and garbage in week six. Unique gift messages, production batch IDs, or full metafield JSON blobs will hit (other). If you need a rare value for support, keep it in BigQuery or the order admin. GA4 dimensions want a closed list.
Registration after a messy name is permanent. You cannot edit the parameter name. You create a new dimension and you live with a dead slot until you archive the old one. I stage the name in a spreadsheet before anyone clicks Save.
Consent still wraps collection. If analytics_storage is denied you may get cookieless pings or nothing. Check the CMP before you spend an hour on a missing key.
Duplicates still inflate Items purchased. Theme plus app plus GTM will make yellow look like a hero. Deduplicate with transaction_id first. WooCommerce block checkout and Shopify wallets skip the page a plugin was watching, so the custom keys exist on view_item and vanish on purchase. Test Shop Pay, Google Pay and the block checkout on purpose.
How to measure after you register the dimensions
You measure after you register the dimensions by pairing each item-scoped dimension with an item-scoped metric and by reconciling a handful of SKUs to the order admin.
Start in Ecommerce purchases. Add one custom item dimension as a secondary dimension. If the column is (not set) for most rows, the parameter is missing on purchase, not on the PDP. If the column is populated on views in an Exploration but empty on purchases, the thank-you path is the bug.
Build a funnel Exploration that stays item-scoped: Items viewed, Items added to cart, Items purchased, broken by metal or fabric. That is the conversation merchandising wanted. Do not drop Purchases (the event metric) onto that canvas and then argue about incompatibility.
DebugView is still the daily tool. I keep the DebugView help next to Tag Assistant. I want the custom key on the item, not only in an event-parameter dump.
Reconcile weekly. Pick ten SKUs that sold. Compare Items purchased for that item_id plus the custom dimension to units in admin. Timezone first. Refunds second. Ads audiences can read registered custom dimensions only if the value was on the events that built the audience. Do not promise a metal audience if metal is PDP-only.
I do not invent a conversion lift from registering a dimension. Measurement quality is the outcome. When the storefront itself changes I quote published figures only: Their Nibs at 31 percent more conversions and 48 percent more orders, and Magento retail conversion work at $2.5 million year-on-year sales. Clean item dimensions are how you see which attributes moved with those projects.
Related work on this site
Related work on this site is the catalogues that already force extra product facts into the storefront, which is the same work that belongs in the items array. Retail conversion at scale is Magento operations where range and stock were daily levers. Their Nibs is Shopify sleepwear where fabric and fit sit on the PDP. Tamannaah Fine Jewellery is Shopify Plus jewellery, where metal and collection are the catalogue. If you are still wiring base events, start with GA4 ecommerce events and GA4 key events for ecommerce.
FAQ
Which catalogue fields belong in GA4 item-scoped custom dimensions?
Catalogue fields that belong in GA4 item-scoped custom dimensions are stable, low-cardinality product facts that merchandisers already use and that are not already prescribed item parameters. Metal, stone, fabric, fit, range and a simple stock state are the ones I register first. Unique messages, serials and raw JSON do not belong there.
Do GA4 item-scoped custom dimensions work if purchase has no items array?
GA4 item-scoped custom dimensions do not work if purchase has no items array. Revenue may still appear. Item reports and item-scoped dimensions will not. Send the same item objects you used on add_to_cart, including the custom keys, and keep item_id aligned with the SKU in admin.
How many GA4 item-scoped custom dimensions should a mid-market store register?
A mid-market store should register only the GA4 item-scoped custom dimensions someone will open every week. On a standard property that ceiling is 10. I usually start with four or five. You can keep sending unused custom item parameters until a merchandiser asks for the next cut.
Can Shopify Analytics replace GA4 item-scoped custom dimensions?
Shopify Analytics cannot replace GA4 item-scoped custom dimensions when you need the same cut in GA4 Explorations, Ads, or a property that also includes Magento or WooCommerce. Shopify's analyticsQueryable metafield capability is for ShopifyQL inside Shopify. I still send the matching key on the GA4 items array when those tools have to agree.
Keep reading
Contact if you want this kind of work on a live store.