User Properties

User properties are attributes you attach to a visitor in GA4 — subscription plan, customer tier, lifecycle stage — that persist across every event the person sends until you change them. Where an event parameter describes one moment, a user property describes the person having the moments. GA4’s data model gives them their own scope, their own limits (25 per property, with 24-character names and 36-character values), and their own registration path. This entry covers what belongs in a user property and what does not, the setup mechanics, the limits that bite, and the difference from event parameters and User-ID that trips up most new implementations.

What a User Property Is

Think of GA4’s data as a ledger of events, each stamped with context. Some context is momentary — which button, which page, what price. Some context is durable — this visitor is on the pro plan, came in through the partner channel, prefers the German interface. User properties carry the durable kind. Set once, they ride along silently on every subsequent event from that user, on that device, until overwritten.

That persistence is what makes them powerful in analysis. Filter any report or exploration by plan = pro and every metric — engagement, conversion, retention — splits by a fact about the person, not about the session. The same fact drives audiences: “all users whose tier is enterprise” is one condition, not a chain of event gymnastics.

What Belongs in a User Property (and What Does Not)

• Good candidates: subscription plan, account type (free / trial / paid), customer segment, signup cohort, language preference, loyalty status, internal-user flag for filtering staff traffic.
• Wrong scope: anything that changes per event — page, product, amount. Those are event parameters. A value you would expect to differ between two events five minutes apart is not a property of the user.
• Forbidden outright: personally identifiable information. Names, emails, phone numbers and precise locations must never appear in a user property — the values surface in reports and exports, and PII in Analytics violates Google’s terms. Identity belongs in User-ID (as an anonymous key), never in a property value.

One nuance worth knowing: GA4 already collects a set of user dimensions on its own — device category, browser, geography, language. Check the predefined dimensions before spending a custom slot; a property that duplicates device category wastes one of your 25.

Setting User Properties

With gtag.js, a single call sets any number of properties, ideally early on the page and before events fire:

gtag('set', 'user_properties', {
  plan: 'pro',
  signup_cohort: '2026-q1'
});

In Google Tag Manager, user properties are rows in the GA4 tag configuration, usually fed from data layer variables your backend renders. Server-side, the Measurement Protocol accepts a user_properties object on any payload — the right channel for facts your frontend does not know, like a billing upgrade processed overnight.

Timing discipline matters here just as with User-ID: a property set after the first events of the page leaves those events carrying the old value (or none). Set properties before the configuration call processes events, and re-assert them on every page — they persist per device in GA4’s collection, but your tag should not rely on that when a login state can change mid-visit.

Registration: Collected Is Not Reportable

Like custom event parameters, a custom user property is invisible to standard reports until you register it as a user-scoped custom dimension (Admin → Custom definitions). Registration is prospective only — data collected before it stays out of reports, though the BigQuery export carries everything regardless. The standard tier allows 25 user-scoped custom dimensions, which conveniently matches the 25-property collection limit: in a disciplined setup, every property you collect is worth a slot.

The Limits That Bite

The 36-character value cap is the one that catches teams: verbose values like enterprise-annual-contract-renewed fit, barely, and anything longer truncates silently — no error, just a mangled value in reports. Keep values short, coded and stable: ent-annual beats a sentence. The 24-character name cap punishes namespacing habits imported from other tools (subscription_billing_type is already 25 characters and one too many).

User Properties vs the Neighbours

• vs event parameters — parameters describe the event, properties describe the user. The limits differ (25 per event vs 25 per property), the custom-definition scopes differ, and mixing them up costs analysis flexibility later.
• vs User-ID — the User-ID says who the user is (an identifier); properties say what the user is (attributes). They work best together: identity from User-ID, segmentation from properties.
• vs audiences — an audience is a saved group built from conditions; user properties are among the best conditions to build them from. The property is raw material, the audience is the product.

A Worked Example: Plan-Based Analysis End to End

The lifecycle of one useful property, for a SaaS with free and pro tiers:

1. Decide the vocabulary. plan with values free, trial, pro — short, coded, stable. Written down where the team can see it.
2. Set it at authentication. The backend renders the plan into the data layer; the GA4 tag maps it to a user property before the first event of the page. The Measurement Protocol sends the same property when billing changes it server-side.
3. Register plan as a user-scoped custom dimension the same day — every day before registration is reporting data lost.
4. Use it everywhere at once: a report filter (plan = pro) splits engagement by tier; an audience (“plan = trial, active in last 7 days”) feeds activation campaigns; an Exploration compares funnels across the three values on one screen.
5. Watch the transitions. When a user upgrades, subsequent events carry pro while their history keeps trial — user properties in reports reflect the value at event time. For “current state” analysis regardless of history, the audience (which re-evaluates) is the right tool, not the raw dimension.

That last distinction — value-at-event-time versus current value — is the subtlest thing about user properties and the source of most “the numbers look wrong” conversations. Neither view is wrong; they answer different questions.

Auditing Your 25 Slots

Slots are scarce enough to deserve an annual audit. Two habits keep the inventory honest: first, list the registered user-scoped dimensions against the properties actually arriving in DebugView — orphaned registrations (dimension exists, property no longer sent) and dark properties (sent, never registered) both accumulate in mature setups. Second, archive what analysis stopped using: archiving a custom dimension frees its slot, and the underlying data remains in BigQuery if a question ever resurrects it. A property that no report, audience or exploration touched in a year is a slot someone else needs.

Verifying the Setup

Fire a test visit with DebugView open: user properties appear in their own panel, updating as your calls execute. Check three things — the property appears at all, its value survives un-truncated, and it is present from the first event of the page rather than only after some interaction. Then confirm the registered dimension fills in reports over the following day; user-scoped dimensions apply to new data only, so yesterday’s traffic will never backfill.

Frequently Asked Questions

How many user properties does GA4 allow?

25 per property on the standard tier, with names up to 24 characters and values up to 36. Overruns fail silently — extra properties are dropped and long values truncated without any error surfacing.

Why is my user property not showing in reports?

Almost always: it was never registered as a user-scoped custom dimension, or it was registered after the data arrived. Registration is prospective. If DebugView shows the property but reports stay empty, registration timing is the answer.

Can I store the user’s email in a user property?

No. Emails are PII and prohibited in any Analytics field, properties included. Store an anonymous key in User-ID and keep human-readable identity entirely inside your own systems.

Related Terms

• Event Parameters — the per-moment counterpart to per-user properties
• User-ID — identity, where properties are attributes
• Event — what user properties ride along on
• Data Layer — the usual source of property values
• Debug View — where to verify properties arrive intact
• Device Category — a predefined user dimension you get for free