Custom Events

GA4 custom events are user-defined event hits that you create when none of Google’s automatic, enhanced measurement, or recommended events match the action you need to track. They power product analytics (feature adoption, demo requests, pricing-page CTAs, custom video milestones) and convert into conversions (now called Key Events in GA4) when the action drives revenue. This guide explains how custom events differ from the other three event categories, the snake_case naming rules Google enforces, GTM and gtag.js implementation paths, parameter limits, custom dimensions registration, and the mistakes that quietly break your reports.

What Are Custom Events in GA4 (vs Automatic vs Enhanced Measurement)

GA4 splits events into four buckets distinguished by who names them and who fires them. Custom events sit in the bucket where you control both the name and the trigger.

• Automatic events fire on every property without configuration: first_visit, session_start, user_engagement. Reserved names; you cannot redefine them.
• Enhanced measurement events are toggleable per data stream. Seven categories: page_view, scroll, click (outbound), view_search_results, video_start/progress/complete, file_download, form_start/submit. You flip a switch in Admin → Data Streams → Enhanced measurement; Google decides the trigger logic.
• Recommended events are Google-published names with required parameter schemas. Use purchase, add_to_cart, sign_up, generate_lead, login exactly as documented and you unlock ecommerce reports plus Google Ads conversion import.
• Custom events fill everything else. You invent the name (demo_request, pricing_cta_click, filter_applied) and you fire it via data layer, GTM, or gtag.js.

The decision rule: before naming a new custom event, check the recommended events catalog. Naming a checkout completion order_done instead of purchase means GA4’s ecommerce reports stay empty. Reserved-name collisions silently drop your event entirely.

Event Naming Convention: snake_case Best Practices

Naming is where most custom event implementations rot. Six months in, properties accumulate buttonClick, BUTTON_CLICK, btn-click, and btnClickV2 for the same action. GA4 treats each as a separate event name and burns slots from your 500-name limit.

Stick to one convention. The Google recommendation (and the one used across every recommended event) is snake_case, lowercase, verb-first:

• video_play, not VideoPlay or video-play
• signup_submit, not signupSubmit or SignupSubmitted
• pricing_cta_click, not PricingCtaClick
• filter_applied, not filterApplied

Hard rules GA4 enforces (events that violate get rejected silently, with no error message in the UI):

• Maximum 40 characters in the event name.
• Letters, numbers, and underscores only. No hyphens, spaces, or special characters.
• Must start with a letter (not a digit, not an underscore).
• Cannot use reserved prefixes ga_, google_, firebase_.
• Cannot collide with reserved automatic event names (session_start, user_engagement, etc.).

Document your naming convention in a shared tracking plan before any developer touches the code. The cost of fixing a sprawling event taxonomy after the fact (renaming events without breaking historical reports) is brutal.

Recommended Events vs Custom Events

Before you create a custom event, scan the recommended events list. Each industry has a published catalog with required and optional parameters. Using these names unlocks features custom events cannot:

If your action matches a recommended event, even loosely, use that name. Save custom events for the long tail of product-specific interactions: demo_request, pricing_compare_open, filter_applied, integration_connected, workspace_invited.

Creating Custom Events via GTM (Step-by-Step)

Google Tag Manager is the lowest-friction implementation path. You configure a trigger that fires on the user action, and a GA4 Event tag that sends the event with parameters.

1. Build the trigger. In GTM, go to Triggers → New. Pick a trigger type that matches the action: Click — All Elements for CTAs, Form Submission for forms, Custom Event for anything dataLayer-driven, Element Visibility for “section in viewport” tracking. Add filters: trigger fires when Click Classes contains cta-pricing, for example.
2. Build the tag. Go to Tags → New → GA4 Event. Set the configuration tag to your existing GA4 Configuration tag (the one with your Measurement ID). Set Event Name to pricing_cta_click (snake_case).
3. Add event parameters. Under Event Parameters, add rows for each piece of context: cta_location = {{Click Classes}}, page_section = {{Page Path}}, cta_text = {{Click Text}}. Use built-in or User-Defined Variables to keep values dynamic.
4. Attach the trigger. Under Triggering, pick the trigger you built in step 1.
5. Preview in Debug View. Click Preview in GTM, navigate the test site, perform the action, and confirm the event appears in GTM’s preview pane and in GA4 Admin → DebugView with all parameter values.
6. Publish the container. Submit a new GTM version with a meaningful description so future-you can roll back when needed.

Creating Custom Events via gtag.js (JavaScript)

If you skip GTM and embed gtag.js directly, fire custom events with the gtag('event', ...) call. The signature is straightforward: event name first, then a parameters object.

gtag('event', 'pricing_cta_click', {
  cta_location: 'header',
  cta_text: 'Start Free Trial',
  page_section: 'pricing',
  value: 1
});

For dataLayer-driven setups (recommended even without GTM, because it decouples instrumentation from analytics tools), push to the layer first and let your analytics layer consume:

window.dataLayer = window.dataLayer || [];
dataLayer.push({
  event: 'demo_request',
  form_id: 'demo-modal',
  plan_interest: 'enterprise',
  utm_source: 'linkedin'
});

Server-side custom events use the Measurement Protocol for back-end actions like refunds, subscription renewals, or CRM-driven lead scoring. The protocol bypasses the browser, so you keep tracking even when ad-blockers strip client-side tags.

Custom Event Parameters: Naming and Limits

Parameters describe where, why, and how much the event happened. Each event can carry up to 25 parameters; abusing this allowance is the second most common implementation mistake (after bad naming).

Parameter naming rules mirror event naming: snake_case, max 40 characters for the name, max 100 characters for the value (string parameters). Numeric values can be reported as metrics if you register them as custom metrics.

Three scope categories matter for reporting:

• Event-scoped parameters attach to a single event: value, currency, page_location, video_percent. Most parameters fall here.
• User-scoped parameters describe the user across sessions: user_role, customer_tier, logged_in. Set via gtag('set', 'user_properties', {...}) and they persist across all subsequent events.
• Item-scoped parameters live inside the items[] array on ecommerce events: item_id, item_name, item_category, price, quantity.

Reserved parameter names (page_location, page_referrer, page_title, screen_resolution, language, etc.) are auto-collected on every event; don’t redefine them.

Using Custom Dimensions to Capture Parameter Values in Reports

Here’s the silent-failure pattern that bites everyone: you fire a custom event with parameters, you see the parameters in DebugView, you run a report a week later and the parameter values aren’t there. The data flowed in, but GA4 only surfaces parameters in reports if you register them as custom dimensions (or custom metrics for numeric values).

Registration steps:

1. In GA4, go to Admin → Custom definitions → Create custom dimension.
2. Set Dimension name (display name in reports, e.g., “CTA Location”).
3. Set Scope to Event for event-scoped parameters or User for user properties.
4. Set Event parameter to the exact parameter name you fire (cta_location).
5. Save. Data starts surfacing in reports within 24 hours; backfill is not retroactive.

Limits: 50 event-scoped custom dimensions, 25 user-scoped custom dimensions, and 50 custom metrics per property (Standard property; 360 properties get higher quotas). Audit and prune unused dimensions before you hit the cap, because once registered, names cannot be reused for different parameters.

Mark Custom Events as Conversions (Key Events in 2025+)

In March 2024, Google renamed conversions to Key Events inside GA4 (the term conversion now refers exclusively to ad-platform conversions in Google Ads). The mechanism is identical: flag a high-value custom event and GA4 starts attributing it across reports, audiences, and Ads imports.

To mark a custom event as a Key Event:

1. Go to Admin → Events in GA4. Wait until your event has fired at least once; it must appear in the Existing events list.
2. Toggle the Mark as key event switch on that event row.
3. Optionally, in Google Ads, link the GA4 Key Event as a conversion goal under Tools → Conversions → Goals.

Best practices: keep your portfolio of Key Events small (5 to 10 across the property) and reserve them for actions tied to revenue or pipeline value. Treating every micro-interaction as a Key Event dilutes your macro-conversion bidding signals; reserve smaller wins for micro-conversion tracking through audiences and segments instead.

Limits: 500 Unique Event Names, 25 Parameters, 50 Custom Dimensions

GA4 enforces hard quotas on custom-event volume and configuration. Hitting any of them silently breaks tracking: no warning email, just data quietly missing.

360 properties (the paid tier) get higher quotas: 125 user-scoped dimensions, 250 custom metrics, 50 Key Events. For most teams, the 500-name and 50-dimension caps bite first. Audit your event catalog quarterly with the Admin → Events → DebugView quota usage panel.

For a step-by-step implementation walkthrough including GTM data layer variables and DebugView verification, see: GA4 Custom Events: How to Create, Name, and Limit Them Correctly.

Common Custom Event Tracking Mistakes

The mistakes I see across audits, every one of them silent failures that took weeks to diagnose:

• Re-implementing recommended events under custom names. Naming purchases order_complete means ecommerce reports never populate. Always use the reserved name.
• Inconsistent casing across teams. Frontend fires buttonClick, backend fires button_click, mobile app fires BUTTON_CLICK: three event names, one action, broken funnel reports. Enforce a tracking plan in version control.
• Skipping custom dimension registration. Parameters appear in DebugView but never in reports. Every event-scoped parameter you want in a report needs a registered dimension.
• Sending PII as parameters. Email addresses, phone numbers, free-form names, full addresses: GA4 will sample and reject events containing PII signatures, and you risk GDPR violations. Hash IDs server-side before passing anything user-identifiable.
• Marking too many events as Key Events. Diluting your conversion signal kills Google Ads bidding accuracy. Keep Key Events tied to true business outcomes: 5 to 10 per property.
• Not validating in DebugView before publishing. Always preview GTM containers and watch the event flow in DebugView before pushing to production.
• Ignoring reserved-name conflicts. Custom events named session_start or page_view get dropped. Read the gtag.js events reference for the full reserved list.
• Treating event count as a metric. Event counts inflate when users refresh pages or trigger duplicates. Pair with engaged-session counts and unique users for honest analysis.

Frequently Asked Questions

Related Glossary Terms

• Event: the parent concept covering all four GA4 event categories.
• Enhanced Measurement: the seven auto-collected events you toggle per data stream.
• Trigger: the GTM mechanism that fires a custom event tag.
• Data Layer: the structured object where custom event payloads are staged.
• Tag Management: the discipline of orchestrating tags, triggers, and variables.
• Container: the GTM container that holds your custom event tags.
• Data Stream: the GA4 web/app stream receiving your custom events.
• Measurement Protocol: the server-to-server path for back-end custom events.
• Debug View: the GA4 panel for validating custom event payloads in real time.
• Conversion: the predecessor to “Key Events” terminology in GA4.
• Macro-Conversion: high-value Key Events tied to revenue.
• Micro-Conversion: smaller engagement signals tracked via custom events.

External references: GA4 recommended events catalog · gtag.js events reference · Simo Ahava’s GA4 implementation guide · Modify and create events in GA4