Skip to content

Guide 48 · Ecommerce · GA4 + Tag Manager

Create item-scoped custom dimensions: report on the extra fields you send inside the items array

Checked 11 November 2026 · Verification: reference file checked in Python (figures recomputed from the worked example) · Steps traced to Google's developer docs and Analytics Help, opened 11 November 2026 · 5-minute read

The items array takes up to 27 custom parameters, but none of them can be reported on until you register it as an item-scoped custom dimension — scope Item, locked after save, explorations only.

Expected signal

After step 4, the dimension exists with scope Item and item parameter color. After 24 to 48 hours, a free-form exploration can break add_to_cart items down by Color; standard reports never show it.

Download the reference: the item-scoped-custom-dimensions reference (JSON) (703 bytes, MD5 42320314d253002914db9c725e98d40d). It holds the event parameters, the worked example, and the recomputed figures.

What you need

  • A custom item-scoped parameter already being collected. The worked example is Google's own: a color parameter on the add_to_cart event, so you know the colour of each shirt in the cart. Check it is arriving first, for example in the Event count by Event name card in the Realtime report.
  • Editor or Administrator access at the property level. Creating custom dimensions needs that role; a lower role cannot save one.
  • A name for the dimension. The worked dimension is named Color. Dimension names cannot contain hyphens, but underscores and spaces are allowed.

The trace

  1. Confirm the parameter is being collected before you register it. The color parameter has to arrive in the items array inside add_to_cart events before the dimension can report on it. The worked item is the Stan and Friends Tee at 10.01 with quantity 3, so the event value is 10.01 × 3 = 30.03, and the item carries color: "green". Check the event is arriving in the Realtime report first.
  2. Open Custom definitions. In Analytics, go to Admin, then under Data display click Custom definitions. Then select the Custom dimensions tab and click Create custom dimension. The same path serves event-scoped and item-scoped dimensions; the scope field is what differs.
  3. Fill in the fields and pick scope Item. Dimension name: Color. Scope: Item. Description: the colour of an item. Item parameter: color. The scope and the item parameter cannot be changed after you save the dimension, so check both before clicking Save. A dimension saved with scope Event by mistake cannot be switched to Item; it has to be deleted and created again.
  4. Respect the limits. You can send up to 27 item-scoped custom parameters in the items array, and configure 10 of them as item-scoped custom dimensions on a standard property, or 25 on an Analytics 360 property. Do not create a custom parameter when a predefined dimension already exists: item_brand, item_category, and item_variant already cover brand, category, and variant without any registration.
  5. Use it in an exploration, not a standard report. An item-scoped custom dimension cannot be added to standard reports. To use it, open Explore, create or open a free-form exploration, click + next to Dimensions in the Variables column, open the Custom tab, expand the Custom drop-down, select the dimension, click Confirm, and drag it into Rows or Columns. The dimension becomes usable 24 to 48 hours after the data was sent and the dimension was created, and only for events after registration.

Dead ends

DEAD END — THE WRONG SCOPE. Scope is locked after save. An item parameter registered with scope Event reports the parameter as if it belonged to the event, not to the item, and the values do not line up with the items. Pick Item for anything inside the items array.

DEAD END — LOOKING FOR IT IN STANDARD REPORTS. Item-scoped custom dimensions cannot be added to standard reports. A dimension that is registered correctly and still absent from the Ecommerce purchases report is not broken; it only appears in explorations and audiences.

DEAD END — REGISTERING AFTER THE DATA. The dimension is not retroactive. Events sent before registration can never be broken down by the dimension. Register the dimension in the same week the parameter starts being sent, or the early data can never be broken down by colour.

End state

The Color dimension exists with scope Item and item parameter color, registered from the add_to_cart event where the tee carries color: "green" and the event value is 30.03. After 24 to 48 hours, a free-form exploration breaks the cart items down by colour. The property can send 27 item-scoped custom parameters and configure 10 of them on a standard property.

Sources

Checked 11 November 2026. The steps above are the ones in Analytics Help, opened 11 November 2026. No step was run inside a live Analytics property, because that needs a Google sign-in and this site does not sign in as anyone. The figures were recomputed in Python: 10.01 × 3 = 30.03. The reference file was checked the same way.