[GA4] Create item-scoped custom dimensions

Create item-scoped custom dimensions if you have an ecommerce website or mobile app so you can analyze the additional information you collect in the items array within an ecommerce event like 'purchase' or 'add_to_cart.' The information you collect in the items array is sometimes called item-scoped parameters.

Before you begin

• Don't create a custom item-scoped parameter if a predefined dimension already exists.
• Add the custom item-scoped parameter to your website or mobile app.
• Make sure the custom item-scoped parameter is being collect. For example, you can select an event in the Event count by Event name card in the Realtime report.
• Make sure you're an editor or administrator.

Limits

To give you the flexibility to choose from a larger pool of parameters without having to retag your site or app, you can send up to 27 item-scoped custom parameters, of which you can configure:

• 10 item-scoped custom parameters for standard properties
• 25 item-scoped custom parameters for Analytics 360 properties

Instructions

1. In Admin, under Data display, click Custom definitions.
   Note: The previous link opens to the last Analytics property you accessed. You can change the property using the property selector. You must be an Editor or above at the property level to create item-scoped custom dimensions.
2. Select the Custom dimensions tab
3. Click Create custom dimensions.
4. Complete the following fields:

   Field	Description
   Dimension name	Enter a unique name for the new dimension. The name you choose will appear in your reports and ad platform. You can't use hyphens in the name, but you can use underscores and spaces instead.
   Scope	Select Item to create an item-scoped custom dimension. You can't change this field after you save the new dimension.
   Description	Optional text used to identify the item-scoped custom dimension.
   Item parameter	Enter the name of the custom item parameter in your website or app code. You can't change this field after you save the new dimension.

5. Click Save.

Example

In addition to the recommended event parameters for the add_to_cart event, you configure a color item-scoped parameter so you know the color of each shirt in the add_to_cart event. To analyze the color event parameter, you create the following item-scoped custom dimension:

• Dimension name: Color
• Scope: Item
• Description: The color of an item
• Item parameter: color

Next steps

Analyze the custom dimension in a report

You can't add an item-scoped custom dimension to standard reports.

Analyze the custom dimension in an exploration

To add the custom dimension to a free-form exploration:

1. In Google Analytics, click Explore on the left.
2. Create or open a free-form exploration.
3. In the Variables column on the left, click + next to Dimensions.
4. Click the Custom tab at the top.
5. Select the custom dimension.
6. Click Import.
7. Drag the dimension from the Variables column.
8. Drop the dimension into Rows or Columns in the Settings column.

Build an audience using the dimension

To build an audience using the custom dimension:

1. In Admin, under Data display, click Audiences.
   Note: The previous link opens to the last Analytics property you accessed. You can change the property using the property selector. You must be a Marketer or above at the property level to build an audience using the dimension.
2. In the top right, click New audience.
3. Click Create a custom audience.
4. Expand the Add new condition drop down.
5. Select Custom, then select the custom dimension.
6. Add a filter, then click Save.