Skip to content

Guide 87 · Admin · GA4 + Tag Manager

Custom user properties in GA4: register a user-scoped dimension so the property shows in reports

Checked 11 November 2026 · Verification: figures recomputed in Python 3, shown in the downloadable file · Steps traced to Google help and developer pages, opened 11 November 2026 · 6-minute read

Sending a user property is only half the job. Register it as a user-scoped custom dimension in Custom definitions, or it will not appear as a dimension in your reports.

Expected signal

After the trace, Custom definitions lists a user-scoped custom dimension with the exact user property name, and the dimension is available for reports and audiences.

Download the reference: the custom user properties reference (JSON) (419 bytes, MD5 8aa05c1eb8377649d3a7834ab8492e1c). It holds the worked example from this guide with every figure recomputed. The file was built for this guide and checked the same day; it was not exported from a live property.

What you need

  • A user property already being sent by the tag, confirmed in DebugView.
  • Editor access at property level.
  • The exact user property name, copied from the tag configuration.

The trace

  1. Confirm the property is being sent before you register it. Open DebugView and check that events carry the user property. Registering a property that is never sent creates a dimension with no data.
  2. Open Admin, then under Data display click Custom definitions, then the Custom dimensions tab. Click Create custom dimensions.
  3. Enter the dimension name. Use a readable name, such as Membership tier. Hyphens are not allowed in the name; underscores and spaces are.
  4. Set Scope to User. The scope cannot be changed after you save, and a user-scoped dimension describes the user, not one event. The companion guides cover event and item scopes.
  5. Enter the User property name exactly as the tag sends it, for example loyalty_tier. This field cannot be changed after you save either. A mismatch here is the most common reason a dimension stays empty.
  6. Click Save, then wait. As with other custom definitions, the dimension becomes usable in reports 24 to 48 hours after the data was sent and the dimension was created. Check the worked example in the download: a property sent on 11 November is usable between 12 and 13 November.

Dead ends

DEAD END — REGISTERING BEFORE SENDING. A dimension registered before the property is sent has no data to show. Send first, confirm in DebugView, then register.

DEAD END — A SCOPE YOU CANNOT CHANGE. Scope is locked after save. A user property registered as an event-scoped dimension cannot be converted; you must create a new one.

DEAD END — EXPECTING PAST DATA. Custom dimensions are not retroactive. Data appears only from the point the dimension was created and the data was sent.

End state

The dimension is user-scoped, the user property name matches the tag exactly, and the 24 to 48 hour wait is noted. Past data does not appear; new data does.

Sources

Checked 11 November 2026. The click paths above are the ones in Google's help and developer pages, opened 11 November 2026. No step in this guide was run inside a live Analytics property or a live Tag Manager container, because both need a Google sign-in and this site does not sign in as anyone. The figures on this page were recomputed in Python 3 and are shown in the downloadable file, which was checked the same day. Google moves menu items without warning; if a path on this page no longer matches, the linked help page is the current map.