6 min read

How to Track Custom Dimensions in Google Analytics 4

Custom dimensions let you track data specific to your business — subscription tier, user segment, account type — alongside GA4's standard metrics. Without them, you're stuck analyzing behavior without context. Here's how to set them up and start capturing them.

Register Custom Dimensions in GA4

GA4 needs to know about your custom dimensions before it captures them. You can register them in the UI or let GA4 auto-discover them from your data.

Register a custom dimension in the GA4 interface

Go to Admin > Custom definitions > Custom dimensions. Click Create custom dimension. Name it (e.g., subscription_tier), set the scope to Event or User, and pick a parameter name that matches what you'll send from your code. The parameter name must match exactly or GA4 won't capture it.

javascript
// After registering 'subscription_tier' as a custom dimension,
// send it with an event. The parameter name must match GA4 exactly.
gtag('event', 'sign_up', {
  'subscription_tier': 'premium',
  'value': 99.99,
  'currency': 'USD'
});
Send a custom dimension with an event

Or let GA4 auto-register custom dimensions

GA4 can auto-discover custom parameters after you send them a few times. If you don't want to pre-register, just send custom parameters with your events. After ~24 hours, they'll appear in Custom definitions as unregistered. You can then register them officially to keep your config clean.

javascript
// Send custom data without pre-registering it.
// After 24 hours, it'll show up in Custom definitions as unregistered.
gtag('event', 'purchase', {
  'company_size': 'enterprise',
  'industry': 'saas',
  'value': 499
});
GA4 will auto-discover these custom parameters
Tip: Use snake_case for parameter names and keep them under 40 characters. GA4 has a 25 custom dimension limit per property, so plan your schema early.

Send Custom Dimensions with Events

Event-scoped custom dimensions track data that changes per action. Use this for things like transaction value, feature used, or trial length.

Send custom data alongside standard event parameters

Pass your custom dimension as a parameter in the gtag('event', ...) call. GA4 will link it to that event. You can send multiple custom dimensions in one event.

javascript
// Track a conversion with custom context
gtag('event', 'conversion', {
  'value': 150,
  'currency': 'USD',
  'account_type': 'startup',
  'feature_adopted': 'dashboard',
  'days_in_trial': 14
});
Multiple custom dimensions in a single event

Track custom dimensions with page views

Page views are events too. Send custom dimensions with gtag('event', 'page_view', {...}) or use gtag.config() to set them globally for all events on that page.

javascript
// Set custom dimensions for all events on this page
gtag('config', 'G-XXXXXXXXXX', {
  'page_title': 'Pricing Plans',
  'user_role': 'admin',
  'ab_test_group': 'variant_b'
});

// Or with a specific event
gtag('event', 'page_view', {
  'page_path': '/pricing',
  'pricing_plan': 'enterprise'
});
Custom dimensions with page views
Watch out: Event-scoped custom dimensions only apply to that single event. If you need the same dimension for every event from a user, use user properties instead.

Send Custom Dimensions as User Properties

User-scoped custom dimensions persist across all events for that user. Use this for attributes that don't change often — plan tier, company, cohort.

Set a custom user property with gtag.set()

Call gtag('set', {...}) to send custom data that applies to the entire user session. GA4 will include these properties in all future events from that user.

javascript
// Set user properties that persist across all events
gtag('set', {
  'user_segment': 'power_user',
  'company_industry': 'healthcare',
  'signup_source': 'partner'
});

// All subsequent events will include these properties
gtag('event', 'feature_click', {
  'feature_name': 'export_data'
});
User properties are inherited by all future events

Set user properties at initialization

You can also pass user properties directly in the gtag.config() call when you initialize the measurement. This ensures they're captured from the first event.

javascript
// Initialize with user properties
gtag('config', 'G-XXXXXXXXXX', {
  'user_id': 'user_12345',
  'user_segment': 'early_adopter',
  'product_tier': 'premium',
  'has_custom_domain': true
});
Set custom dimensions on initialization
Tip: User properties persist until you explicitly change them or the user clears their cookies. Update them when status changes (e.g., plan upgrade) so your segments stay accurate.

Common Pitfalls

  • Forgetting to register custom dimensions in GA4 — unregistered parameters may not appear in reports or will show as 'unspecified'.
  • Mismatching parameter names — if your code sends subscription_tier but you registered subscription-tier, GA4 won't link them.
  • Sending custom dimensions inconsistently — if only 10% of your events include a dimension, your reports will be sparse and hard to analyze.
  • Hitting GA4's 25 custom dimension limit — plan your dimensions upfront so you don't run out of space mid-project.

Wrapping Up

Custom dimensions turn raw event data into business context. Register them upfront, match your parameter names exactly, and decide whether each dimension should be event-scoped or user-scoped. Your analytics will be far more useful when you can segment by subscription tier, account type, or feature adoption. If you want to track custom dimensions automatically across Google Analytics 4 and your other tools, Product Analyst can help.

Track these metrics automatically

Product Analyst connects to your stack and surfaces the insights that matter.

Try Product Analyst — Free