How to Import Custom Event Data Into GA4

Custom-event data import widens existing GA4 events with external event metadata. Google describes it as a reporting or query-time join using standard fields and event-scoped custom dimensions as keys. It does not create new events. Start with the reporting question and compare campaign, item, user, event, and custom-event import types. Select custom-event import only when the external fields belong at event scope and the join keys exist in collected data.

Write the intended report, dimensions, owners, source system, freshness requirement, and rollback need before creating the source. If the goal is offline events that were never collected, use the event-data path instead. If the goal is catalog attributes, review item data. Choosing the wrong type can create incompatible scope, unavailable audiences, or a processed join that is harder to reverse.

Google allows at least one and up to two key dimensions for custom-event data, drawn from supported platform, page or screen, and event-scoped custom-dimension fields. Select keys that are present, consistent, and specific enough for the intended join. Profile recent GA4 values and the external source before building the file. Preserve case, formatting, and null behavior in the contract.

Avoid a broad key that maps unrelated events to the same metadata. Do not use personal identifiers, email addresses, phone numbers, or unrestricted free text as join keys. If a custom dimension used as a key is deleted, Google says the import fails. Give key dimensions durable names, owners, and change control, and document which event collection creates each value.

Custom-event data import supports at least one and up to ten import dimensions under Google's documented details. Mapped custom dimensions must be event scoped. Use only fields needed for the approved report, with controlled values and a data dictionary. Keep the field name, external column, GA4 dimension, scope, allowed values, source owner, and sensitivity classification in the manifest.

Google notes that typed event parameters not associated with a custom dimension do not surface in reporting until an appropriate custom dimension exists. Create and validate reporting dimensions deliberately. If an import-field custom dimension is later deleted, the import can continue but that dimension is no longer available in reporting. Treat dimension deletion as a governed schema change, not routine cleanup.

Review every column for personal data, sensitive values, reserved names, unsupported scope, and unnecessary detail before upload. Hashing does not automatically make an identifier appropriate for Analytics. Follow the organization's consent, privacy, and data-sharing policies and obtain legal review where required. Keep the raw extract in an approved private system and create the smallest upload artifact needed for the reporting purpose.

Reject duplicate keys because Google warns they can cause reporting problems such as double counting. Validate headers, data types, encoding, row count, unique key combinations, nulls, allowed values, and sample joins. Keep a file fingerprint, schema version, generation time, source query, reviewer, and approval. Never invent missing values to improve the match rate.

GA4 requires Editor access to create the custom-event data import. In Data import, choose custom event data, select CSV or an approved SFTP source, and map key and import fields. Test with a bounded file containing known synthetic or approved records. Google states that source mappings cannot be changed after the source is saved; a different mapping requires a new source or deletion and recreation of the old one.

Before the production upload, capture the source name, mapping, property, platform, schema, and file fingerprint. Use a distinct test source if the limits and governance allow it. Do not upload a broad production file to discover whether the schema is correct. Validate the small result first, then expand only after the join and reports match the written contract.

Google says imported custom-event data can take up to twenty-four hours to become available. Review the import status, percentage imported, and match rate after the documented processing window. Google describes match rate for custom-event import as the share of keys found in the property within the recent ninety-day comparison window. Keep unmatched rows as a separate investigation set rather than altering keys until they appear to match.

Build a report with the key, imported dimension, event count, date, platform, and a known control record. Confirm that imported values join only to intended events. Compare aggregate totals before and after without assuming the imported metadata changed the underlying event count. Query-time widening affects how dimensions appear in reporting; it is not evidence that the external system created or corrected the original Analytics event.

For repeated uploads, keep the schema stable and validate every file. Google explains that imported rows with the same key set overwrite existing imported values, while other rows persist. Record batch ID, source fingerprint, row count, unique keys, import time, status, match rate, and owner. Use SFTP only with approved key management and the public-key verification workflow documented in GA4.

Because custom-event data uses a reporting-time join, Google says deleting the source removes the custom-event imported values from Analytics reports. Treat deletion as a consequential rollback requiring approval, impact review, export of the source manifest, and post-deletion verification. Do not assume the same behavior for collection or processing-time imports. Maintain separate runbooks by import type and report observed outcomes without attributing changes in business performance to the import alone.