What Are GA4 Custom Dimensions and Why Do Ecommerce Sites Need Them?

Google Analytics 4 automatically collects a standard set of ecommerce parameters when you implement the GA4 purchase event—things like item name, item ID, price, quantity, and revenue. But most real ecommerce businesses track more about their products than the GA4 standard schema provides. You might want to analyze sales by product brand, product category tier, fabric type, sale status, supplier, product margin tier, or any of a dozen other attributes that are specific to your catalog. GA4 custom dimensions let you capture and report on exactly these kinds of attributes.

A custom dimension is a user-defined attribute that you attach to events, users, or items in GA4. Item-scoped custom dimensions are specifically designed for ecommerce—they attach to individual products within a purchase or view_item event, allowing you to break down metrics like revenue, quantity, and conversions by your custom product attributes. Without item-scoped custom dimensions, you are limited to whatever GA4 decided to include in its standard ecommerce schema. With them, you can answer questions like “which product brand generates the highest revenue per unit?” or “do sale items have a higher return rate than full-price items?”

Item-Scoped vs. Event-Scoped vs. User-Scoped Custom Dimensions

GA4 offers three scopes for custom dimensions, and choosing the right scope is critical. Event-scoped custom dimensions attach to a specific event. If you fire a page_view event with a custom parameter page_template: "product_listing", that parameter is available as an event-scoped custom dimension. It tells you something about that particular event occurrence.

User-scoped custom dimensions attach to a user and persist across sessions. Examples include membership tier, customer segment, or A/B test variant assignment. These let you analyze behavior differences between user groups over time.

Item-scoped custom dimensions are the most specialized. They attach to individual items within the items array of an ecommerce event. When a user purchases three products in one transaction, each product can carry its own set of item-scoped custom dimensions. This is the scope you need for product attributes like brand, category, supplier, or margin tier. GA4 reports can then break down revenue and conversion metrics by these item attributes.

Step 1: Define Your Custom Dimensions in GA4

Before you can use custom dimensions in reports, you must register them in the GA4 interface. Go to GA4 Admin → Custom Definitions → Custom Dimensions → “Create custom dimensions.” For an item-scoped custom dimension, fill in three fields. The “Dimension name” is the human-readable label that appears in GA4 reports—for example, “Product Brand.” The “Scope” must be set to “Item.” The “Description” is optional but useful for documentation. The “Event parameter” is the key name exactly as it appears in the items array of your event data—for example, item_brand.

Create one custom dimension registration for each item attribute you want to track. GA4 allows up to 10 item-scoped custom dimensions on the free Analytics tier (GA4 360 allows 100). Plan your custom dimension list carefully before implementation. Once registered, GA4 starts processing the parameter into the custom dimension going forward—it does not backfill historical data.

Step 2: Send Item Attributes in the GTM dataLayer

With custom dimensions registered in GA4, you now need to send the attribute data in your ecommerce events. The data must be included in the items array of the dataLayer push. Here is an example of a purchase event dataLayer push with custom item attributes:

dataLayer.push({
  event: 'purchase',
  ecommerce: {
    transaction_id: 'TXN-98765',
    value: 159.97,
    currency: 'USD',
    items: [
      {
        item_id: 'SKU-001',
        item_name: 'Merino Wool Sweater',
        price: 89.99,
        quantity: 1,
        item_brand: 'Alpine Co.',
        item_category: 'Clothing',
        item_category2: 'Knitwear',
        item_variant: 'Navy Blue',
        // Custom attributes as extra keys in the item object:
        fabric_type: 'Merino Wool',
        sale_status: 'full_price',
        supplier_region: 'New Zealand',
        margin_tier: 'high'
      },
      {
        item_id: 'SKU-044',
        item_name: 'Thermal Base Layer',
        price: 69.98,
        quantity: 2,
        item_brand: 'Alpine Co.',
        item_category: 'Clothing',
        item_category2: 'Base Layers',
        fabric_type: 'Polyester Blend',
        sale_status: 'on_sale',
        supplier_region: 'Portugal',
        margin_tier: 'medium'
      }
    ]
  }
});

The custom attributes (fabric_type, sale_status, supplier_region, margin_tier) sit alongside the standard GA4 item parameters within the same item object. GA4 picks these up automatically through the GTM GA4 tag as long as you have registered the corresponding custom dimensions in the GA4 interface using these exact parameter names.

Step 3: Configure GTM to Pass Custom Item Parameters

In Google Tag Manager, your GA4 Purchase tag needs to be configured to pass the custom item parameters to GA4. Open your GA4 event tag for the purchase event. In the tag configuration, find the “Items” section. If you are using the Ecommerce data from the dataLayer, ensure “Use Data Layer” is enabled. GTM will automatically pick up all fields from the ecommerce.items array in the dataLayer, including your custom parameters—as long as they are present in the item objects.

Verify this is working in GTM Preview Mode. Trigger a test purchase on your site with GTM preview active. Click on the purchase tag in the preview panel and examine the “Items” section in the tag details. You should see your custom item parameters (fabric_type, sale_status, etc.) listed alongside the standard item fields. If they appear here, they are being sent to GA4 correctly.

Step 4: Use Custom Dimensions in GA4 Reports

Once data has been flowing for at least 24–48 hours, your item-scoped custom dimensions will appear as dimensions in GA4’s Explore reports and in the standard ecommerce reports. In Explore, create a Free Form exploration. In the Dimensions panel, click the “+” button and search for your custom dimension name (e.g., “Product Brand”). Add it to the Rows section. Add “Purchase Revenue” as a Metric. GA4 will display revenue broken down by the product brand attribute you are now tracking.

You can also combine multiple item-scoped custom dimensions in a single report. For example, add both “Sale Status” and “Product Brand” as dimensions to see which brands perform better at full price versus during sales. Or add “Supplier Region” and “Margin Tier” to identify which regional suppliers are driving your highest-margin sales. These are the kinds of insights that were simply impossible in Universal Analytics and remain difficult in GA4 without custom dimensions.

Querying Custom Item Dimensions in BigQuery

If you have enabled the GA4 BigQuery Export, your custom item parameters are also available for SQL analysis. In BigQuery, custom item parameters sit inside the items repeated record within each event row. Here is how to query revenue by your custom margin_tier attribute:

SELECT
  item.item_name,
  (SELECT value.string_value FROM UNNEST(item.item_params) WHERE key = 'margin_tier') AS margin_tier,
  SUM(item.quantity * item.price) AS revenue
FROM
  `your_project.ga4_export.events_*`,
  UNNEST(items) AS item
WHERE
  _TABLE_SUFFIX BETWEEN '20260401' AND '20260417'
  AND event_name = 'purchase'
GROUP BY
  item_name, margin_tier
ORDER BY
  revenue DESC;

Custom item parameters in BigQuery follow the same nested structure as event parameters—they live inside an item_params array within each item object and must be unnested using the same UNNEST pattern. Once you understand this pattern, you can build any revenue segmentation analysis you need directly in BigQuery, without any sampling or reporting limitations.

Common Mistakes to Avoid

The most common mistake is a mismatch between the parameter name in the dataLayer and the parameter name registered in GA4. If your dataLayer uses margin_tier but you registered the custom dimension with parameter name marginTier (camelCase), GA4 will not map them together. GA4 parameter names are case-sensitive. Always use snake_case (underscores, all lowercase) for custom parameters—this matches GA4’s own conventions and prevents case-sensitivity issues.

Another mistake is sending too many distinct values for a custom dimension. GA4 has a cardinality limit—if a single dimension has more than a few hundred thousand distinct values, GA4 will start bucketing the less common values into an “(other)” category. If you plan to use order_id or product_sku as a custom dimension for granular item-level analysis, route this analysis through BigQuery instead of relying on the GA4 interface, which handles high-cardinality dimensions poorly.

Conclusion

GA4 item-scoped custom dimensions for ecommerce product attributes unlock an entirely new level of merchandising and marketing analysis. By enriching your purchase events with attributes like brand, fabric type, sale status, and margin tier, you can answer business questions that the standard GA4 schema was never designed to address. The implementation requires careful planning—registering dimensions in GA4 before collecting data, using consistent snake_case parameter names, and avoiding high-cardinality abuse—but the payoff is an analytics setup that serves your buyers, merchandisers, and marketers with the specific segmentation they actually need.