GA4 Custom Dimensions and Metrics: The Complete 2026 Reference

What are GA4 custom dimensions and metrics?

Custom dimensions let you attach additional context to GA4 events and users — information beyond GA4's automatically collected fields. Custom metrics let you track numerical values beyond GA4's standard metrics. The critical concept that most implementations miss: custom dimensions are not automatically reportable in GA4 standard reports.

They must be registered in GA4 Admin (Admin → Custom Definitions → Custom Dimensions) before they appear as report dimensions. The raw parameter data is collected either way — but without registration, you can't use the dimension in standard reports or Looker Studio. You can only access it in GA4 Explorations or BigQuery.

The three dimension scopes

Event-scoped custom dimensions

Attached to a specific event. The dimension value is valid only for that event instance.

Examples:

• form_id — which form triggered a lead event
• product_category — category of item viewed
• lead_type — contact/demo/trial on a generate_lead event
• video_title — title of a video viewed

Limit: 50 event-scoped custom dimensions per property.

Registration:

Admin → Custom Definitions → Custom Dimensions → + Create → Scope: Event → Event parameter: exact key name used in your dataLayer/gtag calls.

User-scoped custom dimensions

Attached to the user, persisting across all their sessions.

Examples:

• subscription_plan — free/starter/pro
• customer_tier — bronze/silver/gold
• lifetime_purchase_count — 0/1/2-5/6+
• login_status — logged_in/not_logged_in

Limit: 25 user-scoped custom dimensions per property.

Registration:

Admin → Custom Definitions → Custom Dimensions → + Create → Scope: User → User property: exact key name used in gtag('set', 'user_properties', {...}).

Persistence: User-scoped dimensions persist on the device's GA4 cookie until overwritten. They are not cross-device unless User-ID is implemented.

Item-scoped custom dimensions

Attached to individual items in the e-commerce items array.

Examples:

• item_material — cotton/polyester/wool
• item_collection — spring2026/autumn2025
• item_margin_tier — high/medium/low

Limit: 10 item-scoped custom dimensions per property.

Registration:

Admin → Custom Definitions → Custom Dimensions → + Create → Scope: Item → Item parameter: exact key name used in the items array.

Custom metrics

For numerical values you want to aggregate:

Examples:

• product_margin — margin value per item purchased
• lead_score — numerical lead quality score
• engagement_score — calculated engagement value
• subscription_mrr — monthly recurring revenue per user

Limit: 50 custom metrics per property (event-scoped).

When to use custom metrics: When a standard GA4 metric doesn't exist for your business value. totalRevenue is standard; product_margin (revenue minus COGS) is a custom metric.

The cardinality limit and (other)

Each custom dimension has a cardinality limit of 500 unique values per day per dimension. If your custom dimension receives more than 500 distinct values in a single day, the excess values are bucketed into (other).

Common causes of high cardinality:

• Sending transaction IDs as a custom dimension (every order ID is unique — immediately exceeds 500 on any busy day)
• Sending timestamps or session IDs as a custom dimension
• Sending URL slugs that include user-specific query parameters
• Sending product IDs for a large catalogue (>500 SKUs, each viewed in a day)

The cardinality test: Before registering a custom dimension, ask: "How many distinct values will this dimension have per day?" If the answer is >500, it will generate (other) and be unreportable in standard reports.

High-cardinality data belongs in BigQuery, not in custom dimensions.

Naming conventions that prevent collisions

With 50 event-scoped slots available, naming conventions matter. Two analysts independently creating dimensions for similar things with different names consume separate slots and create confusion.

Recommended naming convention:

Event parameter key (in code): form_id

GA4 registration name: "Form ID"

Custom dimension internal name: form_id

This alignment prevents the common situation where the parameter is named formId in the dataLayer, form_id in GTM, and "Form ID" in GA4 — three different names for the same data.

The registration delay and retroactive data

Critical behaviour: When you register a custom dimension in GA4 Admin, GA4 begins populating it in reports from the registration date forward. Historical event data where the parameter was collected before registration is NOT retroactively available in the standard reports.

But: The raw parameter data IS available in BigQuery for dates before registration — if BigQuery export was enabled when the events were collected. This means:

1. Enable BigQuery export early (from day one of a property)
2. Register custom dimensions in GA4 Admin as early as possible
3. For historical analysis of dimensions you forgot to register, use BigQuery

The implementation checklist

When adding a new custom dimension to your implementation:

1. ✅ Choose scope (event, user, or item) — matches the data's permanence
2. ✅ Define the parameter key (snake_case, descriptive)
3. ✅ Implement in GTM (add to GA4 event tag parameters or user property setting tag)
4. ✅ Register in GA4 Admin (Admin → Custom Definitions → same day as deployment)
5. ✅ Verify in GA4 DebugView (confirm parameter appears on events within 24 hours)
6. ✅ Test in GA4 Free Form Exploration (confirm dimension is available and values are correct after 24-48 hours)
7. ✅ Document in measurement plan (parameter name, scope, description, first use date)