> Site index: https://usehardal.com/llms.txt > Every content route also serves markdown at .md # GA4 Data Import: Types, CSV Setup, and Examples Use GA4 Data Import to upload item, campaign cost, user, and event data. See every import type, CSV setup, join behavior, examples, and common errors. Source: https://usehardal.com/google-analytics-4-data-import Published: 2025-11-04 Updated: 2026-08-22 Author: Ecem Bircan Category: Analytics --- > GA4 Data Import joins external data to events already in your Google Analytics property. For product attributes such as color, style, and material, choose **Item data** and map the file to `item_id`. For non-Google ad spend, choose **Campaign data**, the import type previously called Cost data. An online retailer that already sends `item_id` and `price` with ecommerce events can upload one file containing color, style, material, or other catalog fields. GA4 matches each row to the item in its existing event data. The correct feature for that job is **Data Import**, with **Item data** selected. ## What is GA4 Data Import? GA4 Data Import brings data from a CRM, inventory system, point-of-sale system, or advertising platform into Google Analytics 4. It matches the imported rows to collected Analytics data through one or more keys. Google calls the configured file or connection an **import source**. The feature handles several jobs: - Add product metadata such as color, size, style, or margin to ecommerce reporting. - Add cost, click, and impression data from non-Google campaigns. - Add CRM attributes such as loyalty tier or customer lifetime value to known users. - Add offline events that were not captured by a tag, SDK, or real-time connection. - Add custom metadata to existing events for reporting. The imported fields can appear in reports, comparisons, explorations, or audiences, depending on the import type and its join mode. [Google's Data Import documentation](https://support.google.com/analytics/answer/10071301) lists the current types, source options, and limits. ## GA4 Data Import types The current GA4 import flow offers six choices. Pick the type before you build the CSV because each one accepts a different schema and uses a different join. | GA4 import type | What it adds | Typical key | Join mode | |---|---|---|---| | Campaign data, formerly Cost data | Non-Google campaign cost, clicks, and impressions | Source, medium, and date. Campaign ID and name are recommended | Reporting/query time | | Item data | Product catalog fields such as name, brand, category, color, style, and size | `item_id` or a supported item-scoped dimension | Reporting/query time | | User data by User ID | CRM attributes such as loyalty tier or lifetime value | `user_id` | Collection/processing time | | User data by Client ID | User attributes when your implementation relies on a GA client or app instance ID | Client ID or App Instance ID plus Stream ID | Collection/processing time | | Events data | Offline events that GA4 did not collect in real time | The required web or app event fields | Collection/processing time | | Custom event data | Extra metadata for events already collected | Standard fields or event-scoped custom dimensions | Reporting/query time | Older guides call Campaign data **Cost data import**. Google renamed the feature, but searches, training material, and parts of the GA4 documentation still use both terms. If you see a certification question asking which two data types are joined at reporting or query time, the older expected answer is **Cost data and Item data**. Current GA4 also supports **Custom event data** as a reporting/query-time import. ## Which tool should you use to upload item data? For Google Analytics reporting, use **GA4 Data Import > Item data**. This is the right choice when ecommerce events already contain an item key and another system owns the descriptive fields. The phrase "upload item data to ad platforms" can describe a different task: - To enrich GA4 reports, use GA4 Item data import. - To submit products for Shopping or Performance Max ads, use a [Google Merchant Center product data source](https://support.google.com/merchants/answer/14990942) and link it to Google Ads. - To submit products to Meta, TikTok, or another ad platform, use that platform's catalog or feed tool. GA4 Item data import does not publish a product catalog to an ad network. It joins inventory data to Analytics events so you can report on product behavior. ### Item data import example Suppose GA4 already receives this ecommerce item with a `view_item`, `add_to_cart`, or `purchase` event: ```json { "item_id": "SKU-1042", "item_name": "Linen shirt", "price": 79.00 } ``` Your inventory system contains more attributes. A CSV for Item data import could look like this: ```csv item_id,item_brand,color,style,material SKU-1042,Example Brand,mustard,relaxed,linen SKU-1043,Example Brand,purple,regular,cotton ``` Map `item_id` as the schema key. Map standard item fields directly and map business-specific fields such as `color`, `style`, or `material` to item-scoped custom dimensions. Create those custom dimensions before the upload. [Google's Item data guide](https://support.google.com/analytics/answer/10071144) confirms that Item data can join catalog fields to historically collected and ongoing ecommerce events. It can also replace an item value in reports when the uploaded value and collected value use the same field, so check the file before importing it. ## How to import a CSV into GA4 You need Editor access at the property level. Then follow this flow: 1. Open **Admin** in Google Analytics. 2. Under **Data collection and modification**, select **Data import**. 3. Click **Create import source** and give the source a specific name, such as `Inventory catalog` or `Microsoft Ads cost`. 4. Select the import type. This choice controls the fields and join behavior. 5. Select an available source. Manual CSV and SFTP are standard options. Connected databases, cloud storage, Google Sheets, and advertising platforms are available for certain campaign imports. 6. Upload the file or configure the connection. 7. Map each source column to the matching Analytics field. Mark the fields GA4 should use as the schema key. 8. Review the mapping and click **Import**. 9. Check the import history, percentage imported, and match rate where GA4 provides them. Do not put duplicate key combinations in the file. Repeated `item_id`, `user_id`, or campaign-key rows can cause double counting or other reporting errors. The mapping is fixed after you save an import source. You can upload another file with the same fields or a subset of them. To change the schema, delete the source and create a new one. Google documents this behavior in its [guide to import sources](https://support.google.com/analytics/answer/14243300). ## Campaign data import, formerly Cost data import Campaign data import combines non-Google advertising data with the revenue and key events already measured in GA4. Use it for Microsoft Advertising, Meta, TikTok, Snap, email, affiliate, or other campaign data that does not arrive through a native Google product link. A campaign CSV can use this structure: ```csv utm_id,utm_campaign,utm_source,utm_medium,date,impressions,clicks,cost,currency bing_123,spring_sale,bing,cpc,2026-08-20,12000,420,875.40,EUR ``` GA4 requires these dimensions: - Campaign source, matching `utm_source` - Campaign medium, matching `utm_medium` - Date in `YYYY-MM-DD` format - Currency in ISO 4217 format when you import cost Include at least one metric: clicks, cost, or impressions. Campaign ID (`utm_id`) and campaign name (`utm_campaign`) are optional, but Google recommends both. The values must match the campaign parameters collected on your landing-page sessions. Matching is case-sensitive, so `Facebook` and `facebook` create different values. A perfect CSV will still have a poor match rate if the ad URLs use different source, medium, campaign, or ID values. Because Campaign data uses a query-time join, GA4 can combine an upload with events it has already processed. You can then compare non-Google cost per click and return on ad spend in acquisition and advertising reports. Google's [Campaign data import guide](https://support.google.com/analytics/answer/10071305) includes the current schema and a downloadable CSV template. ## Reporting-time and processing-time joins GA4 joins imported data in one of two ways. The mode determines whether an upload can affect historical GA4 reporting. ### Reporting or query time Campaign data, Item data, and Custom event data join when GA4 runs a report query. These imports can enrich previously processed GA4 events when the keys match. If you delete the import source, GA4 stops applying the joined values to reports. Query-time data is not available while you create audiences in Analytics or segments in Explorations. Item data has additional processing behavior, but Google classifies it as a reporting/query-time import in the current setup flow. ### Collection or processing time User data and Events data are applied while GA4 processes data. They do not join to Analytics events that were already processed. Deleting the source stops future joins, but it does not remove values already written to processed events. User data can still qualify a known user for an existing audience after import. For reporting, that user must return and generate activity after the upload. ## Can you import historical data into GA4? GA4 Data Import cannot migrate historical Universal Analytics data into a GA4 property. UA and GA4 use different data models, and a Data Import source expects keys from the destination GA4 property. You can enrich historical data that GA4 already collected when you use a query-time type: - Campaign data can join past cost, click, and impression rows to matching GA4 campaign data. - Item data can add or replace catalog fields for matching items in past and ongoing GA4 ecommerce events. - Custom event data can add metadata to matching historical GA4 events. User data does not backfill already processed GA4 activity. Events data creates event records from an offline source; it does not convert a Universal Analytics report into GA4 events. ## Does GA4 have a Data Import API? Google does not document a public GA4 Admin API endpoint for uploading Data Import files. The old Management API Data Import methods apply to Universal Analytics, not GA4. The GA4 developer products have separate jobs: - The **Data API** reads reports. - The **Admin API** manages supported property configuration. - **Measurement Protocol** sends web and app events. - **Data Import** uploads or connects external datasets through the GA4 Admin interface. For recurring imports, use SFTP or one of the source connections available for your import type. Google's [GA4 developer overview](https://developers.google.com/analytics/devguides/collection/ga4) lists the current public APIs, and none exposes Data Import file uploads. ## Common GA4 Data Import errors ### The keys do not match The values in the file must match what GA4 collected. Check spelling, case, whitespace, date format, ID format, and UTM naming. For user imports, your measurement setup must send the same `user_id`, Client ID, or App Instance ID used in the file. ### The custom dimension has the wrong scope Create item-scoped custom dimensions for Item data, user-scoped dimensions for User data, and event-scoped dimensions for Custom event data. Create them before uploading the file. ### The file contains duplicate keys Keep one row per complete key. Two rows with the same item or campaign key can cause double counting or other reporting errors. ### The schema changed after setup GA4 does not let you edit a saved field mapping. Delete the import source and create a replacement when you need different key or import fields. ### The upload contains personal information Do not upload names, email addresses, phone numbers, or other personally identifiable information through User data import. Use non-identifying IDs that already exist in your GA4 implementation. ### The data has not appeared yet An accepted upload is not instant. Google says Item, User, and Custom event data can take up to 24 hours to appear. Check the source history and match rate before changing the file. ## Where Hardal fits Data Import adds external context after GA4 has events to match against. Hardal collects first-party events server-side and routes them to GA4 and other destinations. If browser-side collection is losing events or the same payload needs to reach several tools, see Hardal's [server-side analytics](https://usehardal.com/analytics) and [Google Analytics 4 destination](https://usehardal.com/destinations/google-analytics-4). Use Data Import for the catalog, CRM, and campaign fields that belong in a join. Keep the event stream in your collection pipeline.