Topic: Tracking Quality

Custom dimensions in GA4: setting up and auditing

Bernhard Prange · 2026-06-01 · Updated 2026-06-16 · 10 min read

Custom dimensions are the lever that turns generic GA4 tracking into a genuinely analysable data basis. By default GA4 does not know whether a visitor was logged in, which article category they looked at or whether they are a premium customer. Custom dimensions make exactly this kind of information visible - in reports, in explorations and in the BigQuery export.

The catch: custom dimensions only work when two things come together - sending the parameter and a setup step inside the GA4 interface. Forget one of them and the dimension stays empty. That is why they are among the most common sources of error we see in audits. This article explains, step by step, what scopes mean in practice, how the setup really works and where typical setups go wrong.

What are custom dimensions in GA4?

Custom dimensions are your own, self-defined attributes that make additional event or user properties analysable in GA4 - that is, information GA4 does not capture by default. Typical examples: article_category, login_status (logged in yes/no) or membership_level.

Once a custom dimension is set up, you can use it everywhere GA4 offers dimensions: as a primary or secondary dimension in standard reports, as a column or filter in explorations, when building audiences, and as a dedicated column in the BigQuery export.

Dimension vs. metric: A dimension describes an attribute (the "what" - e.g. the article category), a metric is a measurable number (the "how much" - e.g. the number of purchases). So custom dimensions extend the attributes of your data, not the metrics.

The three scopes - and what they mean in practice

The scope determines what a value refers to: a single event, the user overall, or a single e-commerce item. You make this decision once, when you register the dimension - and it cannot be changed afterwards. That is why it pays to understand the scope up front.

Event-scoped: one value per event

An event-scoped dimension describes a single event. The value applies to exactly that one event and can change again with the next event.

Practical example: on the view_item event you send the parameter article_category with the value "Sneakers". If the same user looks at a jacket next, the next view_item sends the value "Jackets". In reports you can now, for example, analyse the conversion rate per article category or build a "views by category" table.

In the UI, an event-scoped dimension shows up wherever you analyse events - for instance as a secondary dimension in the "Events" report or as a breakdown in a free-form exploration. Event scope is the most common case; use it whenever the attribute belongs to the moment of the action.

User-scoped: a value that sticks to the user

A user-scoped dimension describes the user across sessions. The value is set once as a user property and stays attached to the user until it is overwritten - including in later visits.

Practical example: membership_level with the value "gold". No matter which events the user triggers, GA4 assigns them "gold" until their level changes. This answers questions such as "how do gold members behave compared to free users?" - across several sessions.

In practice you mainly use user-scoped dimensions for building audiences and for user-level analysis. Important: user properties are set differently from event parameters (see the setup section below) - one of the most common mix-ups.

Item-scoped: one value per product

An item-scoped dimension describes a single article inside an e-commerce event. It lives in the items array that you send with events like add_to_cart or purchase.

Practical example: you add material = "leather" or delivery_time = "24h" to each product in the cart. This lets you break revenue down by material or delivery time - in addition to the built-in item fields such as item_category. Item scope is e-commerce specific; the standard property offers the fewest slots here (10).

Which scope should you choose?

A simple rule of thumb:

• Does the attribute belong to the moment of the action? → event scope.
• Does it describe the person behind it (persistently)? → user scope.
• Does it describe a single product in the cart? → item scope.

If in doubt, event scope is usually the safe choice. A wrongly chosen scope can only be fixed by deleting and recreating the dimension - with a new name and a break in the data.

Setting up a custom dimension - step by step

Here is the crucial point where most setups fail: a custom dimension is made of two parts. The parameter must, first, arrive with the event and, second, be registered in the property. Only the registration turns a raw parameter into an analysable dimension. Without this setup step, GA4 does collect the value (visible in the raw export) but shows it in no standard report.

Step 1: Send the parameter reliably

First, the value has to reach GA4 at all - on every relevant event and with exactly the name you register later (case matters).

Event parameter directly via gtag.js:

gtag('event', 'view_item', {
  article_category: 'Sneakers'
});

Via Google Tag Manager: in the GA4 event tag, add a parameter article_category under "Event Parameters" and pull the value from a dataLayer variable.

A user property (for user-scoped dimensions) is set differently - not as an event parameter:

gtag('set', 'user_properties', {
  membership_level: 'gold'
});

In GTM this happens in the "User Properties" section of the GA4 tag. This distinction matters: if you accidentally send membership_level as an event parameter, it cannot be registered as a user-scoped dimension.

Step 2: Register the dimension in GA4 (the mandatory setup step)

This is the step that tends to be forgotten. Here is how:

1. Open Admin and go to Data display > Custom definitions.
2. Tab Custom dimensions → button Create custom dimensions.
3. Fill in the fields:
   • Dimension name: the human-readable display name in reports, e.g. "Article category".
   • Scope: event, user or item - choose correctly now, it cannot be changed later.
   • Description: briefly document what the dimension stands for (helps the team and the audit).
   • Event parameter or User property: enter the exact parameter name you send in step 1 (article_category). Typos or a different spelling are the classic mistake here.
4. Save.

Mind the limits: 50 event-scoped, 25 user-scoped, 10 item-scoped in the standard property. So do not create dimensions "just in case" - only what you actually analyse.

Step 3: Check that it works

• Immediately: in DebugView (with debug mode or GTM preview enabled) you see in real time whether the parameter arrives with the event and what value it has.
• After 24-48 hours: the values appear in standard reports and explorations.
• Important: custom dimensions do not work retroactively. Values are only filled from the moment of registration onward - everything before stays (not set). So register the dimension before an important campaign, not after.

Common sources of error - with examples

In audits we keep seeing the same patterns. Here are the typical cases with concrete examples:

• Sent but never registered. The dev team dutifully sends article_category with every view_item - but nobody created the dimension in GA4. It does not even appear in the report picker. The value only lives in the BigQuery export. Fix: complete step 2.
• Typo / wrong spelling. Registered is articleCategory, sent is article_category. GA4 finds no match, the dimension stays entirely (not set). Fix: align the names exactly (including case).
• Wrong scope. membership_level was registered as event-scoped instead of user-scoped. Result: you cannot build clean user audiences with it, and the value "jumps" because it only hangs off the individual event. Fix: recreate it as user-scoped and set the user property correctly.
• High cardinality. Someone creates page_url_with_parameters as a custom dimension - with thousands of distinct values due to query strings. Above the daily limits GA4 groups the values under (other), making a detailed analysis impossible. Fix: group/normalise the values up front (e.g. path without parameters).
• Personally identifiable information (PII). An email address or phone number ends up as a custom dimension value in GA4 - a breach of Google's policies and a data-protection problem. Fix: never send PII as a parameter; strip it server-side if in doubt.
• Limit exceeded / dead slots. The 50 event-scoped slots are full of old test dimensions, so a new important dimension can no longer be created. Fix: archive registered but never-sent dimensions.

How the GA4 Auditor checks this

The GA4 Auditor reads your custom definitions via the Admin API and reconciles them with the parameters actually arriving from the BigQuery export. At a glance you see: registered but empty dimensions (typos or never sent), sent but not registered parameters (wasted potential), scope conflicts, and dimensions with suspiciously high cardinality. Instead of clicking through the definitions manually, the gaps are named for you. Check your property now.

Related topics

• GA4 audit checklist - all config checks.
• (not set) in GA4 - source analysis
• BigQuery export for GA4 - custom dimensions in the raw data export.

tracking ga4 datenqualität