Quick answer: A GA4 custom dimension is the bridge between an event parameter you're sending and a dimension you can actually use in reports. Without registering the parameter as a custom dimension, the data is in your event stream but invisible in Explorations and standard reports. The audit checks three things: every parameter you care about is registered, the scope is correct (event vs user vs item), and you haven't hit the 50 / 125 dimension quota.
This post walks through each piece — what registration actually does, when each scope is right, what the quotas are, and the four mistakes we see most often.
What "register a custom dimension" actually does
When you send an event to GA4 with a parameter — say event: page_view, parameter: page_type=pricing — GA4 receives the parameter and stores it on the event row. But you can't filter or break down by page_type in reports until you register it as a custom dimension in Admin → Custom definitions → Create custom dimension.
Registration is what tells GA4 to make the parameter queryable in standard reports, Explorations, audiences, and the API. The data is collected either way — registration controls visibility, not capture.
One important consequence: registration is not retroactive. If you start collecting a parameter on day 1 and register it on day 30, the dimension is empty for days 1–29 in Explorations. The event data exists in the BigQuery export (if enabled) but not in the GA4 UI. Register as early as possible.
The 3 scopes (event, user, item) and when each is right
Event scope
The most common scope. The parameter is captured on a single event and is visible alongside that event. Examples: article_category on a page_view, search_term on a view_search_results, error_message on a custom form_error event.
Use event scope when the value belongs to that specific event, not to the user across all their events. Even if the same value tends to recur (the same user often searches similar terms), use event scope unless you specifically need the value to stick across the whole session.
User scope
The parameter is captured once and applied to every subsequent event from that user until it's overwritten. Examples: plan_tier (free / pro / enterprise), account_age_days, user_segment, company_size.
Use user scope when the value describes who the user is, not what they're doing. You want to be able to break down any event by this dimension regardless of when in the session it was set.
Setting a user-scoped property requires gtag('set', 'user_properties', {...}) or the equivalent GTM tag — it's not just an event parameter. This is the most common gotcha: people send the value as an event parameter and then can't figure out why "user scope" doesn't seem to work. See mistake #1 below.
Item scope
Only applies to ecommerce items inside a view_item, add_to_cart, purchase, etc. The parameter is captured on the item, not the event. Examples: item_color, item_subscription_term, item_warranty_years.
Use item scope when you need to break ecommerce reports down by a product attribute that isn't already a standard item parameter (which include item_id, item_name, item_brand, item_category, etc.).
Quota: 50 event-scoped + 25 user-scoped + 10 item-scoped
GA4 limits how many custom dimensions you can register per property:
- Event-scoped: 50 (GA4 Standard) / 125 (GA4 360)
- User-scoped: 25 (Standard) / 100 (360)
- Item-scoped: 10 (Standard) / 25 (360)
The quotas are per property, not per data stream. Hitting the limit silently — GA4 doesn't email you, it just stops letting you register new ones. If you've inherited a property that's been around for years, the quota is often largely consumed by old dimensions that no longer correspond to events anyone fires.
You can archive unused custom dimensions to free quota — but archiving is permanent. The dimension can't be re-activated; you'd have to create a new one with a different name. Audit aggressively but archive conservatively.
The 4-step audit
Step 1: List every parameter you're sending
Open Admin → Events and inspect 5–10 representative events. Click into each and look at the parameter list. For events sent via GTM, also open your GTM container's tag list and review what parameters are populated. The goal: a complete list of every parameter your container sends.
Step 2: Compare with the registered dimensions
Admin → Custom definitions lists every registered dimension. Match each parameter from step 1 against this list. Any parameter not in the list is invisible in reports — register it (if it matters) or stop sending it (if it doesn't).
Step 3: Verify each dimension has the correct scope
For each registered dimension, click into it and check the scope. The common errors:
- An event-level parameter registered as user-scoped — the dimension will be sparse or empty because the SDK isn't writing it as a user property.
- A user attribute registered as event-scoped — you can only break down events where the parameter happened to be sent, not all events from that user.
Step 4: Check the quota and archive what's dead
On the Custom definitions page, the count of dimensions is visible. If you're over 40 event-scoped (out of 50), audit each one for a recent Last collected date. Anything not collected in 90+ days is a candidate for archiving — but only after you confirm the corresponding event is genuinely retired, not just briefly paused.
4 mistakes we see most often
1. User-scope set via event parameter instead of user_properties
Setting plan_tier=pro as an event parameter and registering a user-scoped custom dimension named plan_tier doesn't work the way you'd expect. The parameter sticks to the event, not to the user. To make it user-scoped, fire gtag('set', 'user_properties', {plan_tier: 'pro'}) once per session, or use a GTM "Set User Properties" tag. Registering the dimension with user scope is necessary but not sufficient — the data has to be sent as a user property, not an event parameter.
2. (not set) flooding a dimension
If a parameter is only sometimes sent — e.g., article_category is sent on blog page_views but not on the homepage — the dimension will show (not set) for events where the parameter wasn't populated. That's expected behavior, but it makes reports messy. Fix: either send the parameter on every relevant event (with a default value like "none") or filter Explorations to only include events where the parameter is populated.
3. Naming a dimension differently from the parameter
You can set the registered dimension's display name to anything ("Article Category") but the Event parameter field has to match the parameter name being sent exactly, including case. article_category ≠ Article_Category ≠ articleCategory. This is a classic 30-minute debugging session waiting to happen.
4. Hitting the 50 quota with old test dimensions
Properties that have been through multiple developers tend to accumulate test_dim_1, experiment_a, old_category_name entries that were created in a sprint, never used, and never cleaned up. Each takes one slot from the 50 event-scoped quota. Run the archive list quarterly.
Frequently asked questions
Are custom dimensions retroactive?
No. Registration only makes future events queryable by that dimension. Events received before registration are not retroactively populated in the GA4 UI. The raw events are in BigQuery export (if enabled) — see our data retention guide for the BigQuery export pattern.
What's the difference between a custom dimension and a custom event?
A custom event is a new event name (the row in your data). A custom dimension is a new attribute on existing events. You can have one custom event with ten registered custom-dimension parameters on it. Custom events count toward the event quota (500 distinct names per property); dimensions count toward the dimension quota separately.
Can I archive a custom dimension and reuse the name?
No. Archiving permanently retires the dimension. You can create a new one with the same display name but you cannot recreate the same internal API name. Be intentional about archiving.
Do custom dimensions work in the API and BigQuery export?
BigQuery: yes, but the parameter appears in the event_params nested array regardless of registration. The "registration" concept is GA4-UI-only — BigQuery has the full parameter data either way. API: yes, registered dimensions are queryable via the GA4 Data API. Unregistered parameters aren't.
How do custom dimensions interact with Consent Mode v2?
If a user has denied analytics_storage, the event is modeled rather than measured — so custom-dimension data isn't captured at the user level for that user. Modeled aggregates may include the dimension, but individual events are missing. See our Consent Mode v2 checklist for the full picture.
What about reporting identity?
User-scoped dimensions interact with reporting identity. If your reporting identity is set to Device-only, user properties still attach to the device identifier — but if the user clears cookies and returns, they appear as a new "user" with no prior user properties. Blended or Observed identity is more durable. This matters most for things like lifetime_value or account_age_days that you want to follow a real human, not a device.
Audit custom dimensions automatically
A Snifflytics audit checks the dimensions you've registered, the scope of each, the quota you've consumed, and which sent parameters aren't yet registered. Run it alongside the 25-point GA4 audit checklist. Start a free audit.