Custom dimensions in Google Analytics 4 let you track custom user and event properties that matter to your business—subscription tier, experiment variant, customer lifecycle stage. Without them, you're stuck with GA4's built-in dimensions. The setup is two-part: create the dimension in Admin, then send the data through gtag.js or the Measurement Protocol.

Register Your Custom Dimension in GA4 Admin

First, tell GA4 what custom data to expect by registering it in the admin console.

Step 1: Open Custom Definitions

Go to Admin > Data Collection and Modification > Custom Definitions. Click Create custom dimension.

javascript

// Custom dimensions are defined in the GA4 admin console
// Navigate to Admin > Data Collection and Modification > Custom Definitions
// Click "Create custom dimension" to register a new one

Custom dimensions must be registered in the UI before you can send data

Step 2: Configure Dimension Name and Scope

Enter a Dimension Name (e.g., subscription_tier). Choose Scope: Event scope applies only to the event it's sent with; User scope applies the dimension to all events in a session. Set the Parameter Name—this must match the parameter you'll send in your code.

javascript

// The parameter name in your code must match the registered name
// Event-scoped example
gtag('event', 'purchase', {
  'subscription_tier': 'premium',  // Parameter name must match
  'value': 99.99
});

// User-scoped example (set once, applies to all events)
gtag('config', 'GA_MEASUREMENT_ID', {
  'subscription_tier': 'enterprise'
});

Match your parameter name exactly to what you registered in Custom Definitions

Step 3: Save and Wait

Click Save. GA4 queues the dimension for activation. Wait a few minutes before sending data—check Real-time reports to confirm it's live.

Send Custom Dimension Data with gtag.js

Once registered, send the data from your website using the Google Analytics gtag library.

Step 1: Load gtag.js

Add the gtag script to your page <head>. Replace GA_MEASUREMENT_ID with your actual Measurement ID from Admin > Property Settings.

javascript

<!-- Google Analytics 4 -->
<script async src="https://www.googletagmanager.com/gtag/js?id=GA_MEASUREMENT_ID"></script>
<script>
  window.dataLayer = window.dataLayer || [];
  function gtag(){dataLayer.push(arguments);}
  gtag('js', new Date());
  gtag('config', 'GA_MEASUREMENT_ID');
</script>

This initializes gtag.js and registers your GA4 property

Step 2: Send Custom Dimensions with Events

For User-scoped dimensions, send them once via gtag('config') and they'll apply to all events. For Event-scoped dimensions, include them in each event. Use the exact parameter name you registered.

javascript

// User-scoped: send once, applies to all events
gtag('config', 'GA_MEASUREMENT_ID', {
  'subscription_tier': 'enterprise',
  'company_size': '500+'
});

// Event-scoped: send per event
gtag('event', 'checkout', {
  'subscription_tier': 'starter',
  'annual_plan': true,
  'value': 29.99,
  'currency': 'USD'
});

// Override user-scoped dimension for specific event
gtag('event', 'upgrade', {
  'subscription_tier': 'premium'  // This event gets 'premium', user still has other value
});

Scope determines persistence: User scope = global, Event scope = per-event

Step 3: Verify Data in Real-Time

Open Reports > Real-time. Trigger an event on your site. Within a few seconds, your custom dimension values should appear. If not, check the Network tab in DevTools to confirm the parameter is being sent.

Use Custom Dimensions in Reports and Segments

After data flows in, slice your analytics by custom dimension.

Step 1: Add Custom Dimensions to Reports

Open any report (e.g., Reports > User > Overview). Click Rows > Add and select your custom dimension. GA4 breaks down the metric (users, conversions, revenue) by each value of that dimension.

javascript

// Query custom dimensions via Google Analytics 4 Reporting API
const analyticsDataClient = new BetaAnalyticsDataClient();

const request = {
  property: `properties/GA_PROPERTY_ID`,
  dateRanges: [{
    startDate: '2024-01-01',
    endDate: '2024-01-31'
  }],
  dimensions: [
    { name: 'customUser:subscription_tier' },  // User-scoped custom dimension
    { name: 'date' }
  ],
  metrics: [
    { name: 'activeUsers' },
    { name: 'conversions' }
  ]
};

const response = await analyticsDataClient.runReport(request);

Prefix custom dimensions with customUser: or customEvent: in the API

Step 2: Create Audiences Using Custom Dimensions

Go to Admin > Audiences. Click Create Audience. Add a condition using your custom dimension (e.g., subscription_tier equals premium). Save it to create a reusable segment.

Common Pitfalls

Parameter names are case-sensitive. If you register subscription_tier in Admin but send SubscriptionTier, GA4 ignores it.
User-scoped custom dimensions must be sent via gtag('config'), not in individual events. Sending them in events applies them only to that event.
Custom dimensions take effect only after registration. GA4 won't backfill historical events with the dimension.
Free GA4 properties are limited to 10 event-scoped and 25 user-scoped custom dimensions. GA4 360 allows more if you hit limits.

Wrapping Up

Custom dimensions let you track business-specific data—subscription tier, feature flag, user cohort—and segment by it in reports. Register the dimension in Admin > Custom Definitions, send the data with gtag.js using the matching parameter name, then use it in reports and audiences. If you want to track this automatically across tools and unify your customer data, Product Analyst can help.

How to Set Up Custom Dimensions in Google Analytics 4

Register Your Custom Dimension in GA4 Admin

Step 1: Open Custom Definitions

Step 2: Configure Dimension Name and Scope

Step 3: Save and Wait

Send Custom Dimension Data with gtag.js

Step 1: Load gtag.js

Step 2: Send Custom Dimensions with Events

Step 3: Verify Data in Real-Time

Use Custom Dimensions in Reports and Segments

Step 1: Add Custom Dimensions to Reports

Step 2: Create Audiences Using Custom Dimensions

Common Pitfalls

Wrapping Up