Add to Preferred Sources
A GA4 custom dimensions guide fills the gap between Google Analytics 4's out-of-the-box data and the segmentation your conversion rate optimisation strategy actually demands. Standard dimensions tell you how many users visited a page. Custom dimensions tell you which users — by plan type, payment gateway, product category, customer tier, or any attribute that your business tracks. For South African sites already generating traffic, that distinction separates a conversion hunch from a conversion diagnosis.
The trigger for building this layer is often a number like the one Baymard Institute tracks: a documented average cart abandonment rate of 70.22% across 50 international studies. Knowing the rate tells you there is a problem.
A properly configured set of custom dimensions — payment method used, user subscription tier, product margin category — tells you where the problem lives and which segment to fix first. Without that layer, you are running CRO on aggregate numbers that hide the real pattern. Read the full SA cart abandonment breakdown for local context before reaching for generic global benchmarks.
Quick Answer
GA4 custom dimensions are attributes you define to extend Google Analytics 4's default data model, letting you segment users, events and products by criteria specific to your business. Standard GA4 properties support up to 50 event-scoped, 25 user-scoped and 10 item-scoped custom dimensions. You register them in Admin → Custom Definitions, they are not retroactive (registration only captures future data), and they power the funnel comparisons, audience segments and conversion analyses that default GA4 reports cannot run on their own.
In This Guide
Not sure which custom dimensions your funnel actually needs?
Send us your current GA4 setup and we will map the gaps between what you are collecting and what your CRO decisions require.
Request a GA4 AuditWhat Are GA4 Custom Dimensions?
A GA4 custom dimension is a user-defined attribute that you send to Google Analytics 4 alongside your standard event data, then register in the Admin panel so it appears in your reports. Standard GA4 dimensions are built in — page title, device category, traffic source, country. Custom dimensions are everything your business needs that Google does not collect by default.
The distinction from custom metrics matters: custom dimensions are descriptive labels (text values — plan type: "pro", payment method: "PayFast", product category: "outerwear"). Custom metrics are numerical values that can be aggregated — revenue per session, items per order. If you want to break a report down by a business attribute, that is a dimension. If you want to calculate an average or run a ratio, that is a metric.
Custom Dimensions vs Standard Dimensions
Standard dimensions are collected automatically by GA4 — page_location, device_category, geo_country, session_source. Custom dimensions are parameters you send deliberately. Neither type is better; they serve different jobs. The mistake is assuming standard dimensions alone are enough for CRO-level segmentation — they almost never are for a business with more than one product line or customer type.
For a GA4 custom dimensions guide to be useful for conversion work, the focus has to be on dimensions that let you compare cohorts: logged-in vs guest users, checkout completed with PayFast vs Peach Payments, products with high vs low margin, users who viewed a discount page vs those who did not. That comparison logic is what drives a useful conversion funnel drop-off analysis.
GA4 Custom Dimensions Guide: Scope Types Explained
Every custom dimension in Google Analytics 4 has a scope, which determines which events the dimension value is attached to. Getting scope wrong is the single most common configuration error — and one you cannot fix after saving.
| Scope | Attaches to | Persists across | SA business example |
|---|---|---|---|
| Event | A single fired event | That event only | form_type on a lead form submission — "quote_request" vs "callback" |
| User | The user profile | All future sessions for that user | customer_tier set at login — "new", "repeat", "vip" |
| Item | Individual products inside an ecommerce items array | The event that contains the product | margin_tier — "high", "medium", "low" — within add_to_cart and purchase events |
Event-scoped dimensions are the most flexible — they attach to any parameter you send with any event. If you fire a click event with a button_text parameter, you can register that as an event-scoped custom dimension and see click rates by button label across all pages.
User-scoped dimensions attach to the user profile and persist across sessions. Set subscription_plan to "pro" when someone upgrades, and GA4 will tag every event from that user going forward with the plan value — letting you compare conversion paths by subscription tier across multiple visits. Critical caveat: user-scoped dimensions are not retroactive within the current session. The moment of registration applies from that event onwards, not backwards to earlier events in the same session.
Item-scoped dimensions are exclusively for ecommerce. They live inside the items array that GA4 uses for product events. If you want to analyse purchase rates by product colour, brand, or supplier, item-scoped is the right choice. Note that item-scoped dimensions do not appear in standard GA4 reports — they are only available in free-form explorations.
Scope Rule of Thumb
If the value changes with every event — use event scope. If the value describes a stable attribute of the person (their tier, plan, or login status) — use user scope. If the value describes a specific product inside a purchase — use item scope. Selecting the wrong scope and saving is permanent; you will need to create a new dimension definition to correct it.
How to Create a GA4 Custom Dimension: Step-by-Step Registration
Creating a Google Analytics 4 custom dimension is a two-step process: first send the parameter with your events (usually via Google Tag Manager), then register it in the GA4 interface so reporting can see it.
Step 1 — Send the Parameter via Google Tag Manager
In your GTM tag for the relevant event, expand the Event Parameters section and add a row. In the Parameter Name field, enter the exact name you plan to use — for example, payment_method. Assign the variable that holds the value. The name must be lowercase, use underscores instead of spaces, and contain no hyphens. Publish your GTM container.
Step 2 — Register in GA4 Admin
Navigate to GA4 Admin → Property → Data Display → Custom Definitions → Custom Dimensions tab. Click Create custom dimension. Enter a human-readable Dimension Name (this is what appears in your reports), select the Scope (event, user or item), and in the Event Parameter field type the exact parameter name from your GTM tag — including matching case. Save.
Step 3 — Wait and Verify
Allow 24–48 hours for the dimension to populate in standard reports. You can verify the parameter is being received sooner using GA4 DebugView (enable preview mode in GTM and fire the event — the parameter should appear in DebugView within seconds). If you see the parameter in DebugView but not in reports after 48 hours, the most common cause is a name mismatch between the GTM parameter name and the GA4 registration.
Payment_Method in GA4 when GTM sends payment_method. GA4 parameter names are case-sensitive. The dimension will register successfully but collect no data. Delete and recreate with the exact matching name.One important constraint: once you save a custom dimension, the Scope and Event Parameter fields are locked. If you chose the wrong scope or misspelled the parameter name, you must create a new definition. The old one can be archived, but it still counts toward your quota until deleted.
GA4 Custom Dimensions for Conversion Rate Optimisation
The conversion value of custom dimensions comes from their ability to segment funnel reports by business-meaningful cohorts — not just by device or channel. Here are the use cases that directly move the needle on conversion work.
Segment Checkout Funnels by User Type
Add a user-scoped user_type dimension with values like "guest", "registered", "repeat_buyer". In a GA4 funnel exploration, apply this as a breakdown dimension. You will see whether your checkout abandonment problem is driven primarily by guest users (often a trust issue — add more payment security signals at checkout) or by logged-in returning customers (often a friction issue — pre-filled details or saved payment methods can close this). The A/B testing process becomes significantly more targeted when you know which cohort to run the test on.
Compare Conversion Rates Across Traffic Sources
Standard GA4 source dimensions split by first-touch or last-touch channel. An event-scoped entry_source dimension on landing page events lets you carry traffic context deeper into the funnel — useful when session_source is getting overwritten by mid-session page loads. This is one of the gaps that GA4 ecommerce tracking addresses at an event level.
Track A/B Test Variants
When you run a split test, send the variant name as an event-scoped custom dimension — ab_variant with values "control" and "treatment". Register it in GA4 and build an exploration that shows your conversion event by variant. This gives you conversion data without needing an external analytics integration, though a proper testing tool is still preferable for statistical significance calculations. See SA conversion rate benchmarks for realistic improvement ranges to target.
Identify High-Value Product Attributes
For ecommerce, item-scoped custom dimensions like product_category_tier ("budget", "mid", "premium") or margin_tier let you run free-form explorations that show which product type drives both volume and margin — not just which product sells most units. This distinction matters when planning promotions or deciding which category pages to prioritise in CRO work.
The Diagnostic Question Custom Dimensions Answer
Standard GA4 tells you your checkout abandonment rate. Custom dimensions tell you it is significantly higher for guest users on mobile arriving from paid social than for logged-in users on desktop from organic search. The segmented view is actionable; the aggregate is wallpaper. Build dimensions that split your audience into groups you can actually do something different for.
Spending budget on traffic but unsure which users are actually converting?
Tell us your funnel structure and we will recommend the exact custom dimension set to make your GA4 data decision-ready.
Get a Funnel ReviewSA-Specific Custom Dimensions Worth Setting Up Now
South African sites should prioritise payment_method (event-scoped) and POPIA-compliant user-tier labels (user-scoped) as their first custom dimensions — two tracking gaps no global GA4 custom dimensions guide addresses. A third worth adding for courier-dependent stores is courier_provider as an item-scoped attribute, which surfaces whether Courier Guy, Aramex or Dawn Wing fulfilment correlates with repeat-purchase rates.
Payment Gateway Tracking
SA stores typically offer multiple local payment options — PayFast, Peach Payments, Yoco, Ozow — alongside card payments. Standard GA4 does not capture which gateway a user attempted or completed. Adding an event-scoped payment_method dimension to your add_payment_info and purchase events reveals whether one gateway has a materially higher abandonment rate at the payment step. If your data shows one gateway completing at a materially higher rate than another, that is a specific optimisation target — not a hunch.
Implementation: push payment_method to the data layer when a user selects or completes a payment option. Common values: "payfast", "peach_payments", "yoco", "ozow", "card_direct". Register as event-scoped in GA4. Run a funnel exploration from add_payment_info to purchase broken down by payment_method.
POPIA Constraints on User-Scoped Dimensions
User-scoped custom dimensions that link to an identifiable individual — customer_tier, subscription_plan, crm_segment — fall within POPIA's data processing rules when combined with other identifying information in your GA4 property. POPIA Section 11 lists consent as one of several lawful bases for processing personal information, alongside contractual necessity and legitimate interests, so consent is not automatically required for every analytics use — but it is typically the most appropriate basis for non-essential tracking.
The practical consequence: with proper POPIA-compliant consent implementation and cookie consent configured correctly, a portion of your visitors will decline tracking. For non-consenting users, user-scoped dimensions return no data — a gap that grows in proportion to how aggressively your consent banner presents the opt-out.
Since mid-2025, the Information Regulator has been testing functional compliance — checking whether scripts actually stop firing when users decline, not just whether a banner is present — and the maximum administrative penalty under POPIA is R10 million. Enforcement practice is ongoing; verify current IR guidance before treating any analytics arrangement as settled. Never send personally identifiable information directly as a custom dimension value (no email addresses, ID numbers, or phone numbers). Use anonymised segment labels instead.
What to Send vs What to Avoid in Custom Dimension Values
Safe: "pro_plan", "repeat_buyer", "vip_tier", "payfast", "mobile_checkout_user" — segment labels with no direct PII.
Not safe: email addresses, phone numbers, SAID numbers, full names, or any value that identifies an individual directly. GA4 terms of service and POPIA both prohibit sending PII through analytics parameters.
GA4 Custom Dimension Limits and How to Prioritise Within Them
Standard GA4 properties have fixed quota limits set by Google's official documentation: 50 event-scoped, 25 user-scoped, and 10 item-scoped custom dimensions per property. Custom metrics follow a separate quota of 50. GA4 360 (enterprise) raises these to 125 event-scoped, 100 user-scoped, and 25 item-scoped.
Most South African SMBs will hit the event-scoped limit before the others. Ten to fifteen dimensions registered without a clear reporting use case consume quota that could be serving your most valuable CRO questions. Before registering a new dimension, ask: which report or exploration will use this, and what decision will change based on the answer?
| Type | Standard GA4 | GA4 360 | Priority guidance |
|---|---|---|---|
| Event-scoped | 50 | 125 | Register only dimensions tied to a live reporting use case |
| User-scoped | 25 | 100 | Limit to stable user attributes — plan, tier, acquisition cohort |
| Item-scoped | 10 | 25 | Prioritise attributes that explain conversion variance (margin, category tier) |
| Custom metrics | 50 | 125 | Separate quota — quantitative values only |
Archived dimensions still count toward your quota until deleted. If you hit the limit and need to add new dimensions, delete unused archived definitions — but allow 48 hours after deletion before the slot is freed.
Seven Common Mistakes That Break Your Custom Dimension Data
- Registering before sending. If you register the dimension in GA4 before your GTM tag is live, the dimension slot exists but collects nothing. Publish your GTM container first, confirm the parameter arrives in DebugView, then register.
- Case mismatches.
Payment_Methodandpayment_methodare different parameters. Always copy-paste from GTM. - Expecting retroactive data. Dimension registration is not retroactive. The day you register is day one of your data. Plan registrations before a major campaign or product launch.
- High-cardinality values. Sending user IDs, timestamps, or session tokens as custom dimension values creates millions of unique dimension values that slow reports and hit GA4's cardinality limits. Use aggregated labels instead.
- Choosing the wrong scope and saving. Once saved, scope cannot be changed. A user-scoped dimension that should have been event-scoped will produce misleading data — the wrong value persisting across sessions. Archive it and create a correctly scoped replacement.
- Not testing in DebugView. DebugView shows parameters in real time. Use it before waiting 48 hours to catch naming errors early.
- Sending PII in dimension values. Email addresses, phone numbers or any directly identifying data in custom dimensions violates both GA4's terms of service and, for South African user data, POPIA obligations. Use anonymised segment labels.
Why South African Businesses Work With Growth Pulse Media on Analytics and CRO
Building a useful GA4 custom dimensions guide for SA operations starts from a practical question: which decision would this dimension change? Setting up a payment_method event-scoped dimension across all four major SA payment gateways — then mapping it through an add_payment_info to purchase funnel exploration — is the type of diagnostic work that surfaces where payment-step drop-off concentrates, and redirects A/B testing budget to the right friction point rather than the busiest page. That is methodology built from running SA ecommerce, not from documentation.
Our conversion rate optimisation service is built on GA4 custom dimension configurations that reflect how SA businesses actually operate: multiple payment gateways with different friction profiles, mobile-dominant traffic that behaves differently from desktop, POPIA-compliant tracking architectures that preserve as much data as consent allows. We work with a deliberately limited client load so the senior team — not a junior analyst — reviews your measurement setup and your CRO hypotheses.
If your GA4 property currently shows aggregate conversion rates without segmentation by user type, product category or payment method, that is the gap. A structured CRO audit only returns actionable findings when those dimensions are already collecting clean data.
Who This Is NOT For
Custom dimensions deliver value in specific conditions. If any of the four situations below describes your business right now, address that constraint first.
Ready to set up custom dimensions that your CRO team will actually use?
Share your current GA4 property and business objectives and we will outline the dimension plan in a 30-minute assessment — no obligation.
Book a 30-Minute AssessmentFrequently Asked Questions
How many custom dimensions can I have in GA4?
Standard GA4 properties support up to 50 event-scoped, 25 user-scoped and 10 item-scoped custom dimensions per property. Custom metrics have a separate quota of 50. GA4 360 enterprise properties have higher limits: 125 event-scoped, 100 user-scoped and 25 item-scoped. Archived dimensions still count toward the quota until permanently deleted.
Are GA4 custom dimensions retroactive?
No. Custom dimension registration in GA4 applies only to data collected after the registration date. Events fired before you register the dimension do not appear in that dimension's report. There is no way to backfill historical data. This is why timing matters — register dimensions before a campaign launch, not after, if you want clean data from the start.
What is the difference between a GA4 custom dimension and a custom metric?
Custom dimensions are descriptive text values — categories, labels, segment names — used for filtering and breaking down reports. Custom metrics are numerical values that can be summed or averaged — items per session, revenue per add-to-cart. If you want to slice a report by a business attribute, use a dimension. If you want to calculate a ratio or aggregate a number, use a metric. Both have separate quotas in GA4.
Do GA4 custom dimensions create POPIA obligations for South African businesses?
They can. User-scoped custom dimensions that link to identifiable individuals — subscription tier, CRM segment, login status combined with a user ID — constitute processing of personal information under POPIA. POPIA Section 11 allows several lawful bases for this, including consent and legitimate interests. Practically: never send personally identifiable information directly as dimension values (no email addresses, phone numbers or ID numbers). Use anonymised labels. For consent-declined visitors, user-scoped dimension data will be absent from your reports if your POPIA compliance implementation is correct.
Can I use GA4 custom dimensions without Google Tag Manager?
Yes, but it is significantly harder to maintain. GA4's gtag.js library allows you to send custom parameters directly from your site code — a developer adds the parameter to the event call and you register it in GA4 Admin. The problem is that every change to a dimension value or a new event requires a code deployment, versus a GTM container publish. For any site that runs conversion optimisation experiments regularly, GTM is the practical requirement.
Build a GA4 Measurement Layer That Drives CRO Decisions
Growth Pulse Media configures GA4 custom dimensions for SA businesses operating PayFast, Peach Payments and Yoco checkout stacks — with POPIA-compliant tracking architecture built in from day one. We work with a limited client roster so every setup gets senior-level attention.
No obligation — we respond within 24 hours.
Start the Conversation