GA4 Custom Dimensions & Metrics: When and How to Use Them

When Do You Actually Need Custom Dimensions? Link to heading

GA4 includes dozens of predefined dimensions and metrics. Before creating custom ones, verify your need isn’t already covered.

Don’t create custom dimensions for:

• Transaction ID (already exists as transaction_id)
• Page title, URL, path (built-in page dimensions)
• Device category, browser, OS (built-in tech dimensions)
• Traffic source, medium, campaign (built-in acquisition dimensions)

Do create custom dimensions when:

• You need business-specific attributes (membership tier, customer segment)
• Your site has unique interactions (quiz answers, configurator selections)
• You track custom product attributes beyond standard ecommerce (subscription type, license tier)
• You need to segment by data not captured by default (logged-in status, A/B test variant)

The rule: custom dimensions are for custom data. If GA4 already captures it, you’re wasting quota.

Understanding Scopes Link to heading

GA4 custom dimensions have three scopes. Choosing the wrong scope causes data to appear incorrectly or not at all.

Event-Scoped Link to heading

Applies to: Single event only

Use for: Context that changes with each action

Examples:

• Search query entered
• Filter selection applied
• Video title watched
• Form field that failed validation
• Coupon code used at checkout

When a user triggers the event, the dimension value applies only to that event. The next event from the same user won’t inherit it.

User-Scoped (User Properties) Link to heading

Applies to: All future events from that user

Use for: Attributes that define the user, not the action

Examples:

• Membership tier (free, premium, enterprise)
• Account creation date
• Customer segment (B2B, B2C)
• Subscription status
• CRM customer ID

Once set, user-scoped dimensions persist across sessions until explicitly changed. They’re retroactively applied in reports, so historical events from that user will show the dimension value.

Important: User properties only apply to future events after being set. If you set membership_tier: 'premium' today, yesterday’s events won’t show that value.

Item-Scoped Link to heading

Applies to: Individual products within ecommerce events

Use for: Product attributes beyond standard ecommerce fields

Examples:

• Product color
• Product size
• Availability status
• Margin tier
• Supplier ID

Item-scoped dimensions only work within the items array of ecommerce events (view_item, add_to_cart, purchase, etc.).

Limitation: Item-scoped dimensions are only available in Explorations, not standard reports.

Quota Limits Link to heading

Plan carefully—once you hit limits, you must wait 48 hours after archiving dimensions before adding new ones.

These limits are per property, not per event. A single dimension can receive data from multiple events.

Implementation: Event-Scoped Dimensions Link to heading

Step 1: Send the Parameter with Your Event Link to heading

In GTM, add the parameter to your GA4 Event tag:

1. Open your GA4 Event tag
2. Under Event Parameters, click Add Row
3. Enter your parameter name and value

Example: Tracking search queries

• Parameter Name: search_term
• Value: {{DLV - Search Query}} (Data Layer Variable)

Or in dataLayer:

dataLayer.push({
  event: 'search',
  search_term: 'blue running shoes',
});

Step 2: Register as Custom Dimension in GA4 Link to heading

Parameters aren’t automatically available in reports. You must register them:

1. Go to Admin > Custom definitions > Custom dimensions
2. Click Create custom dimension
3. Enter:
   • Dimension name: How it appears in reports (e.g., “Search Term”)
   • Scope: Event
   • Event parameter: The exact parameter name (e.g., search_term)
4. Click Save

Note: Data appears in reports within 24-48 hours after registration. The dimension won’t show historical data from before registration.

Implementation: User-Scoped Dimensions Link to heading

User-scoped dimensions use a different mechanism: user properties.

Step 1: Set the User Property Link to heading

Option A: Via GTM GA4 Configuration Tag

1. Open your GA4 Configuration tag
2. Under User Properties, click Add Row
3. Enter property name and value

Option B: Via dataLayer

dataLayer.push({
  event: 'user_data_ready',
  user_properties: {
    membership_tier: 'premium',
    customer_since: '2023',
  },
});

Then in GTM, create a GA4 Event tag that reads these user properties.

Option C: Via gtag.js directly

gtag('set', 'user_properties', {
  membership_tier: 'premium',
});

Step 2: Register as Custom Dimension Link to heading

1. Go to Admin > Custom definitions > Custom dimensions
2. Click Create custom dimension
3. Enter:
   • Dimension name: “Membership Tier”
   • Scope: User
   • User property: membership_tier
4. Click Save

Implementation: Item-Scoped Dimensions Link to heading

Item-scoped dimensions capture product attributes within ecommerce events.

Step 1: Include Parameters in Items Array Link to heading

Your dataLayer push for ecommerce events must include the custom parameters inside each item:

dataLayer.push({
  event: 'view_item',
  ecommerce: {
    items: [
      {
        item_id: 'SKU_12345',
        item_name: 'Running Shoes',
        price: 129.99,
        // Standard parameters above
        // Custom item parameters below
        item_color: 'blue',
        item_size: '42',
        margin_tier: 'high',
      },
    ],
  },
});

Step 2: Register as Custom Dimension Link to heading

1. Go to Admin > Custom definitions > Custom dimensions
2. Click Create custom dimension
3. Enter:
   • Dimension name: “Product Color”
   • Scope: Item
   • Event parameter: item_color
4. Click Save

Reminder: Item-scoped dimensions only appear in Explorations, not in standard reports or the real-time view.

Custom Metrics Link to heading

Custom metrics work similarly to event-scoped dimensions but capture numeric values.

When to Use Custom Metrics Link to heading

• Tracking numeric values beyond standard metrics (custom scores, ratings)
• Measuring business-specific quantities (loyalty points earned, credits consumed)
• Aggregating custom calculations

Implementation Link to heading

Step 1: Send numeric parameter with event

dataLayer.push({
  event: 'loyalty_points_earned',
  points_earned: 150,
});

Step 2: Register in GA4

1. Go to Admin > Custom definitions > Custom metrics
2. Click Create custom metric
3. Enter:
   • Metric name: “Loyalty Points Earned”
   • Event parameter: points_earned
   • Unit of measurement: Standard (or Currency if monetary)
4. Click Save

Practical Examples Link to heading

Ecommerce: Track Coupon Performance Link to heading

Goal: Understand which coupon codes drive the most revenue

Implementation:

// In purchase event
dataLayer.push({
  event: 'purchase',
  ecommerce: {
    transaction_id: 'T12345',
    value: 89.99,
    coupon: 'SUMMER20', // Standard parameter
    coupon_type: 'percentage', // Custom parameter
    coupon_source: 'email_campaign', // Custom parameter
  },
});

Register coupon_type and coupon_source as event-scoped custom dimensions.

Analysis: In Explorations, create a table with Coupon, Coupon Type, Coupon Source vs. Purchase Revenue to identify which coupon strategies work best.

B2B: Track Account Attributes Link to heading

Goal: Segment behavior by company size and industry

Implementation:

// When user logs in or account data is available
gtag('set', 'user_properties', {
  company_size: 'enterprise', // small, mid-market, enterprise
  industry: 'technology',
  contract_tier: 'annual',
});

Register as user-scoped custom dimensions.

Analysis: Compare conversion rates and engagement metrics across company sizes to identify your ideal customer profile.

Lead Gen: Track Form Context Link to heading

Goal: Understand which content drives form submissions

Implementation:

// On form submission
dataLayer.push({
  event: 'generate_lead',
  form_name: 'demo_request',
  content_topic: 'pricing_comparison', // What content they were viewing
  lead_score: 85, // CRM-calculated score
  form_location: 'sidebar', // Where on page
});

Register content_topic, lead_score (as metric), and form_location as event-scoped.

Analysis: Identify which content topics generate the highest-scoring leads.

Ecommerce: Track Product Attributes Link to heading

Goal: Analyze color and size preferences

Implementation:

dataLayer.push({
  event: 'add_to_cart',
  ecommerce: {
    items: [
      {
        item_id: 'SKU_789',
        item_name: 'Classic T-Shirt',
        price: 29.99,
        item_color: 'navy',
        item_size: 'L',
        item_fit: 'regular',
      },
    ],
  },
});

Register as item-scoped custom dimensions.

Analysis: In Explorations, analyze which colors/sizes have highest add-to-cart rates vs. purchase rates to identify sizing issues.

Common Mistakes Link to heading

1. Duplicating Predefined Dimensions Link to heading

Creating a custom dimension for page_title or transaction_id wastes quota. Check GA4’s predefined dimensions first.

2. Wrong Scope Selection Link to heading

Using event-scoped when you need user-scoped (or vice versa) causes data to appear incorrectly:

• If membership tier is event-scoped, you only see it for events where you explicitly sent it
• If search query is user-scoped, all future events inherit that value (wrong)

3. Parameter Name Mismatch Link to heading

The parameter name in GA4 registration must exactly match what you send in the dataLayer. searchTerm ≠ search_term.

4. Expecting Immediate Data Link to heading

Custom dimensions take 24-48 hours to populate. Use DebugView to verify parameters are being sent correctly, then wait for reports to populate.

5. Not Planning for Quota Link to heading

Starting with too many dimensions leaves no room for future needs. Audit quarterly and archive dimensions you no longer use.

Verification Link to heading

1. DebugView Link to heading

Enable debug mode and check:

• Event parameters appear in event details
• User properties show in the user properties card

2. Realtime Report Link to heading

Custom dimensions won’t appear in realtime, but you can verify the base events are firing.

3. Explorations (24-48 Hours Later) Link to heading

Create a Free-form exploration:

• Add your custom dimension as a row
• Add a metric (Event count, Users)
• Verify data populates

Related Resources Link to heading

• GA4 Debug Mode: Complete Troubleshooting Guide

Sources Link to heading

• Google Analytics Help - About custom dimensions and metrics
• Analytics Mania - Guide to Custom Dimensions in GA4
• Optimize Smart - GA4 Scopes Explained