Configure purchase events for Google Analytics 4

Google Analytics is an events-based and session-based analytics service that collects data from websites and apps. Google Analytics 4 properties support privacy controls, such as cookieless measurement, to help your brand better understand the customer journey.

A large percentage of retail sales take place in stores. By providing transactions data for sales that occurred in stores to Google Analytics 4 your brand can use event-based tracking to measure user interactions and conversions.

Amperity uses the Measurement Protocol API to send events to Google Analytics 4. Use a query to map fields in the Unified Transactions and Unified Itemized Transactions tables to Google Analytics 4 purchase events parameters .

Use an orchestration to send purchase events parameters to Google Analytics 4 from Amperity. Query results must include a client_id to ensure purchase events are associated with sessions in Google Analytics 4. Only purchase events that occurred within the previous 72 hours are sent to Google Analytics 4.

Get details

Review the following details before configuring credentials for Google Analytics 4 and before configuring Amperity to send purchase events to Google Analytics 4.

Important

Google Analytics 4 only validates purchase events . Google Analytics 4 does not validate the measurement ID or the API secret associated with the payload. Verify that you have configured the correct measurement ID and added the correct API secret for the measurement ID.

Measurement ID Required The measurement ID associated with your Google Analytics account. All measurement IDs start with “G-” and are followed by a combination of letters and numbers. For example: “G-ABC1DE2FG3”. To find the measurement ID log in to Google Analytics. Expand Data collection and choose Data streams. Select the data stream to which you want to send purchase events. The measurement ID is available under Stream details. Copy the measurement ID and use that value to configure the destination for Google Analytics 4 in Amperity.

API secret Required The API secret generated from the Google Analytics admin console for your brand’s instance of the Measurement Protocol API . To create an API secret for the Measurement Protocol API log in to Google Analytics. Expand Data collection and choose Data streams. Choose the data stream to which you want to send purchase events. Click Measurement Protocol API secrets, and then click Create. Copy the secret and use that value to configure the destination for Google Analytics 4 in Amperity.

Configure credentials

Configure credentials for Google Analytics 4 before adding a destination.

An individual with access to Google Analytics 4 should use SnapPass to securely share “measurement ID” and “API secret” details with the individual who configures Amperity.

To configure credentials for Google Analytics 4 events

	From the Settings page, select the Credentials tab, and then click the Add credential button.
	In the Credentials settings dialog box, do the following: From the Plugin dropdown, select Google Analytics 4. Assign the credential a name and description that ensures other users of Amperity can recognize when to use this destination.
	The settings that are available for a credential vary by credential type. For the “google-analytics-offline-events.” credential type, configure settings, and then click Save. Measurement ID Required The measurement ID associated with your Google Analytics account. All measurement IDs start with “G-” and are followed by a combination of letters and numbers. For example: “G-ABC1DE2FG3”. To find the measurement ID log in to Google Analytics. Expand Data collection and choose Data streams. Select the data stream to which you want to send purchase events. The measurement ID is available under Stream details. Copy the measurement ID and use that value to configure the destination for Google Analytics 4 in Amperity. API secret Required The API secret generated from the Google Analytics admin console for your brand’s instance of the Measurement Protocol API . To create an API secret for the Measurement Protocol API log in to Google Analytics. Expand Data collection and choose Data streams. Choose the data stream to which you want to send purchase events. Click Measurement Protocol API secrets, and then click Create. Copy the secret and use that value to configure the destination for Google Analytics 4 in Amperity. Important Google Analytics 4 only validates purchase events . Google Analytics 4 does not validate the measurement ID or the API secret associated with the payload. Verify that you have configured the correct measurement ID and added the correct API secret for the measurement ID.

Add destination

Use a sandbox to configure a destination for Google Analytics 4. Before promoting your changes, send a test audience, and then verify the results in Google Analytics 4. After verifying the end-to-end workflow, push the destination from the sandbox to production.

To add a destination

	Open the Destinations tab to configure a destination for Google Analytics 4. Click the Add Destination button to open the Destination dialog box. Enter the name of the destination and a description. For example: “Google Analytics 4 events” and “Send events to Google Analytics 4.”.
	Credentials allow Amperity to connect to Google Analytics 4. The credential type is set automatically. You may use an existing credential or you may add a new one. Select an existing credential from the Credential dropdown. – or – Select Create a new credential from the Credential dropdown. This opens the Credential dialog box.
	In the “Destination settings” dialog box, assign the destination a name and description that ensures other users of Amperity can recognize when to use this destination. Configure business user access By default a destination is available to all users who have permission to view personally identifiable information (PII). Enable the Admin only checkbox to restrict access to only users assigned to the Datagrid Operator and Datagrid Administrator policies. Enable the PII setting checkbox to allow limited access to PII for this destination. Use the Restrict PII access policy option to prevent users from viewing data marked as PII anywhere in Amperity and from sending data to downstream workflows.
	Configure the following settings, and then click “Save”.
	After configuring this destination users may use orchestrations to send query results Google Analytics 4.
	Test the connection with Google Analytics 4 by using an audience with a very small membership. For example: 10 or 100 members or the minimum audience size recommended by Google Analytics 4. Send the test audience to Google Analytics 4 and verify the audience is correct in Google Analytics 4. Make adjustments if necessary. Only send full audiences after validation is complete.

Build a query

Information for the query that sends purchase events data to Google Analytics 4 is likely found in three tables in your customer 360 database:

1. Unified Transactions has transaction-level purchase events data.

2. Unified Itemized Transactions has item-level purchase events data. This table may require some customization to align with all of the purchase events parameters supported by Google Analytics 4.

3. A table with unique identifiers from Google Analytics 4. The following example uses a table named Google_Analytics as the source for specific events data points required by Google Analytics 4.

   How to build a Google Analytics table in a customer 360 database

   Google Analytics 4 data should not be made available to Stitch, but must be available from the customer 360 database before purchase events data can be sent to Google Analytics 4.

   1. Configure a data source for Google Analytics 4 data.

   2. Build a custom SQL table in your customer 360 database for Google Analytics 4 data.

   3. Use a SELECT statement and a common table expression to select columns from the Google Analytics 4 source table. The USER_PSEUDO_ID, SESSION_ID, TRANSACTION_ID, USER_ID columns Google Analytics 4 source data must be selected, along with a column with a unique value that matches a unique value in a table evaluated by Stitch and in which rows are assigned an Amperity ID.

   4. Use an INNER JOIN to add the Amperity ID to rows in the Google Analytics 4 database table using the shared unique identifier as the join key.

   For example:

   Google_Analytics table

   WITH ranked AS (
     SELECT
       cp.amperity_id
       ,ga.*
       ,ROW_NUMBER() OVER (
         PARTITION BY cp.amperity_id
         ORDER BY ga.LAST_MODIFIED_TIMESTAMP DESC
       ) AS row_number
     FROM GA4_SOURCE_TABLE AS ga
     INNER JOIN Customer_Profiles_Table AS cp
     ON cp.CUSTOMER_ID = ga.CUSTOMER_ID
   )
   
   SELECT *
   FROM ranked
   WHERE row_number = 1
   

   Replace the names of the CUSTOMER_ID fields within the INNER JOIN with the real column names in your database.

Example: Return results for purchase events

The following SQL example shows how to return purchase events data from three tables and combine them into a single results set that is mapped to the event names required by Google Analytics 4.

WITH Unified_Transactions_Mapped AS (
  SELECT
    amperity_id
    ,Currency AS currency
    ,Store_ID AS location_id
    ,Order_Shipping_Amount AS shipping
    ,Order_Tax_Amount AS tax
    ,Order_Datetime AS timestamp
    ,Coupon_Code AS coupon
    ,CASE
      WHEN DATE_DIFF('day', DATE(Order_Datetime), CURRENT_DATE) >= 540 THEN 'new'
      ELSE 'returning'
    END AS customer_type
  FROM Unified_Transactions
),
Unified_Itemized_Transactions_Mapped AS (
  SELECT
    amperity_id
    ,Item_Discount_Amount AS discount
    ,Purchase_Brand AS item_brand
    ,Product_Category AS item_category
    ,Product_ID AS item_id
    ,Product_Name AS item_name
    ,Item_List_Price AS price
    ,Item_Quantity AS quantity
  FROM Unified_Itemized_Transactions
)

SELECT
  ut.amperity_id
  ,ga.USER_PSEUDO_ID AS client_id
  ,ga.SESSION_ID AS session_id
  ,ga.TRANSACTION_ID AS transaction_id
  ,ga.USER_ID AS user_id
  ,ut.currency
  ,ut.location_id
  ,ut.shipping
  ,ut.tax
  ,ut.timestamp
  ,ut.coupon
  ,ut.customer_type
  ,uit.discount
  ,uit.item_brand
  ,uit.item_category
  ,uit.item_id
  ,uit.item_name
  ,uit.price
  ,uit.quantity
FROM Unified_Transactions_Mapped ut
LEFT JOIN Unified_Itemized_Transactions_Mapped uit ON ut.amperity_id = uit.amperity_id
LEFT JOIN Google_Analytics ga ON ut.amperity_id = ga.amperity_id

Extend the SQL to include any of the additional fields that are accepted by Google Analytics 4.

Use an orchestration to send purchase events data to Google Analytics 4.

Caution

The SQL that your brand requires may be different, depending on which table is the source for unique identifiers from Google Analytics 4.

GA4 events parameters

The following table describes each of the purchase events parameters that are supported by Google Analytics 4. Use a query to map fields in the Unified Transactions and Unified Itemized Transactions tables to purchase events parameters .

The following Google Analytics 4 purchase events parameters must be returned by the query: client_id, currency, item_id, item_name, price, and transaction_id.

All fields, including optional fields, are listed alphabetically, but may be returned by a query in any order.

Field name	Description
affiliation	Optional A product affiliation, such as a supplying company or a brick-and-mortar store location. Applies only to individual items within a transaction and is part of the items array.
client_id	Required Google Analytics is an events-based and session-based analytics service that collects data from websites and apps. Google Analytics 4 properties support privacy controls, such as cookieless measurement, to help your brand better understand the customer journey. A Google Analytics 4 client_id is a pseudonymous identifier created by a first-party cookie stored on a user’s device or browser when they visit a website with a Google Analytics 4 tracking code. For example: GA1.1.489876543.1234567890. The client_id is required to associate purchase events with existing sessions of Google Analytics 4. Must be a non-empty string. For example: 310123456.1739876543.
coupon	Optional A coupon name or coupon code associated with item-specific purchase events. Applies only to individual items within a transaction and is part of the items array.
currency	Required A three character alphabetic ISO 4217 currency code. For example: “USD”, “JPY”, “EUR”, or “GBP”.
customer_type	Optional Indicates a new or returning known customer. A new known customer hasn’t purchased within a given time window. A returning known customer has purchased within a given time window. The values for customer_type must be “new” or “returning”. Google Analytics 4 uses 540 days as the default window. Important If the customer is unknown leave the value blank. For example, when the customer checks out as a guest.
discount	Optional The item-level discount. Applies only to individual items within a transaction and is part of the items array.
item_brand	Optional The brand for an item. Applies only to individual items within a transaction and is part of the items array.
item_category	Optional A series of event parameters that describe the item using your brand’s product catalog taxonomy. Use item_category for the first level within a product catalog taxonomy. Applies only to individual items within a transaction and is part of the items array. Use item_category2 for second level within a product catalog taxonomy. Use item_category3 for third level within a product catalog taxonomy. Use item_category4 for fourth level within a product catalog taxonomy. Use item_category5 for fifth level within a product catalog taxonomy.
item_id	Required A unique ID for an item, such as a stock keeping unit (SKU). Applies only to individual items within a transaction and is part of the items array.
item_name	Required The name of an item. Applies only to individual items within a transaction and is part of the items array.
items	Required An array of item-level details for a transaction, including affiliation, coupon, discount, index, item_brand, item_category fields, item_id, item_list_id, item_list_name, item_name, item_variant, location_id, price, and quantity.
location_id	Optional The physical location of the store at which the transaction occurred. Applies only to individual items within a transaction and is part of the items array. Google place IDs uniquely identify physical locations in Google Places and Google Maps. Place IDs can be mapped to physical store locations. For example: “ChIJEw2sg_lAkFQR25Oh_sq8qRY”.
price	Required The unit price of an item. Applies only to individual items within a transaction and is part of the items array. Note Use the discount purchase events parameter for discounts to the unit price.
quantity	Required The quantity of items purchased. If a quantity is not specified the quantity is “1”. Applies only to individual items within a transaction.
session_id	Recommended A timestamp that identifies the start of a session. For example: 485123456.1767654321.1769876543. Combined with user_id or client_id a session_id uniquely identifies a session.
shipping	Optional The shipping cost for a transaction.
tax	Optional The cost for taxes associated with a transaction.
timestamp	Recommended An ISO 8601 timestamp of when the purchase event occurred. For example: “2025-01-12T14:21:56.000Z”. Important The timestamp must be within 72 hours of sending to Google Analytics 4. The current time is used when the value for timestamp is not provided. Events that occurred outside of the 72 hour window are not sent.
transaction_id	Required A unique identifier within Google Analytics 4 data for a transaction. For example: 316123456.
user_id	Recommended A unique user identifier within Google Analytics 4 that links events to known users. Must be a non-empty string. For example: 12345678.
value	Required The monetary value of the event. Important Amperity calculates the total value for a transaction using the price and quantity purchase events paramaters. value is the sum of the price and quantity for all items purchased in a single transaction, not including shipping costs or taxes.
Custom parameters	Optional Up to 27 custom parameters may be included in purchase events sent to Google Analytics 4.

Map Amperity attributes to GA4 events parameters

The following table describes how to map purchase events parameters that are supported by Google Analytics 4 to attribues in Amperity standard output.

All fields, including optional fields, are listed alphabetically, but may be returned by a query in any order.

GA4 event parameter	Amperity attribute
affiliation	Varies. A product affiliation, such as a supplying company or a brick-and-mortar store location. Applies only to individual items within a transaction and is part of the items array. Use the Store ID field in the Unified Transactions table when the value for location_id is a Google Place ID .
client_id	USER_PSEUDO_ID Google Analytics is an events-based and session-based analytics service that collects data from websites and apps. Google Analytics 4 properties support privacy controls, such as cookieless measurement, to help your brand better understand the customer journey. A Google Analytics 4 client_id is a pseudonymous identifier created by a first-party cookie stored on a user’s device or browser when they visit a website with a Google Analytics 4 tracking code. For example: GA1.1.489876543.1234567890. The client_id is required to associate events with existing sessions of Google Analytics 4. Must be a non-empty numeric string. For example: 310123456.1739876543. The source for client_id is a table in your customer 360 database with Google Analytics 4 data with rows of data assigned an Amperity ID. The client ID is available from a field named USER_PSEUDO_ID.
coupon	Varies. A coupon name or coupon code associated with item-specific purchase events. The source for coupon is a table in your customer 360 database with the coupon name or coupon code.
currency	Currency Google Analytics 4 requires the value for currency to be a three character alphabetic ISO 4217 currency code. For example: “USD”, “JPY”, “EUR”, or “GBP”. Use the Currency field in the Unified Itemized Transactions table when its values are three character alphabetic ISO 4217 currency codes.
customer_type	Customer Type (custom field) Indicates a new or returning known customer. A new known customer hasn’t purchased within a given time window. A returning known customer has purchased within a given time window. The values for customer_type must be “new” or “returning”. Google Analytics 4 uses 540 days as the default window. Use the Latest Order Datetime field in the Unified Transactions table to identify customers who have or have not purchased within a given time window. Define the time window, and then return customers who have purchased as “returning” and customers who have not as “new”. Important If the customer is unknown leave the value blank. For example, when the customer checks out as a guest.
discount	Item Discount Amount The item-level discount. Applies only to individual items within a transaction and is part of the items array. Use the Item Discount Amount field in the Unified Itemized Transactions table.
item_brand	Purchase Brand The brand for an item. Applies only to individual items within a transaction and is part of the items array. Use the Purchase Brand field in the Unified Itemized Transactions table.
item_category	Product Category A series of event parameters that describe the item using your brand’s product catalog taxonomy. Use item_category for the first level within a product catalog taxonomy. Applies only to individual items within a transaction and is part of the items array. Use item_category2 for second level within a product catalog taxonomy. Use item_category3 for third level within a product catalog taxonomy. Use item_category4 for fourth level within a product catalog taxonomy. Use item_category5 for fifth level within a product catalog taxonomy. Use the Product Category field in the Unified Itemized Transactions table for the first level, along with other levels from the same table if they are available.
item_id	Product ID A unique ID for an item, such as a stock keeping unit (SKU). Applies only to individual items within a transaction and is part of the items array. Use the Product ID field in the Unified Itemized Transactions table.
item_name	Product Name The name of an item. Applies only to individual items within a transaction and is part of the items array. Use the Product Name field in the Unified Itemized Transactions table.
location_id	Place ID or Store ID The physical location of the store at which the transaction occurred. Applies only to individual items within a transaction and is part of the items array. Use Google place IDs if your brand has mapped physical store locations to place IDs and has made that data available to your customer 360 database in Amperity. For example: “ChIJEw2sg_lAkFQR25Oh_sq8qRY”. Use the Store ID field in the Unified Transactions table if place IDs are unavailable.
price	Item List Price The unit price of an item. Applies only to individual items within a transaction and is part of the items array. Note Use the discount purchase events parameter for discounts to the unit price. Use the Item List Price field in the Unified Itemized Transactions table.
quantity	Item Quantity The quantity of items purchased. If a quantity is not specified the quantity is “1”. Applies only to individual items within a transaction. Use the Item Quantity field in the Unified Itemized Transactions table.
session_id	SESSION_ID A timestamp that identifies the start of a session. For example: 485123456.1767654321.1769876543. Combined with user_id or client_id a session_id uniquely identifies a session. The source for session_id is a table in your customer 360 database with Google Analytics 4 data with rows of data assigned an Amperity ID. The session ID is available from a field named SESSION_ID.
shipping	Order Shipping Amount The shipping cost for a transaction. Use the Order Shipping Amount field in the Unified Transactions table.
tax	Order Tax Amount The cost for taxes associated with a transaction. Use the Order Tax Amount field in the Unified Transactions table.
timestamp	Order Datetime An ISO 8601 timestamp of when the purchase event occurred. For example: “2025-01-12T14:21:56.000Z”. Important The timestamp must be within 72 hours of sending to Google Analytics 4. The current time is used when the value for timestamp is not provided. Events that occurred outside of the 72 hour window are not sent. Use the Order Datetime field in the Unified Transactions table.
transaction_id	TRANSACTION_ID A unique identifier within Google Analytics 4 data for a transaction. For example: 316123456. The transaction_id is required for deduplicating purchase events and must be a non-empty numeric string. The source for transaction_id is a table in your customer 360 database with Google Analytics 4 data with rows of data assigned an Amperity ID. The transaction ID is available from a field named TRANSACTION_ID.
user_id	USER_ID A unique user identifier within Google Analytics 4 that links events to known users. Must be a non-empty string. For example: 12345678. The source for user_id is a table in your customer 360 database with Google Analytics 4 data with rows of data assigned an Amperity ID. The user ID is available from a field named USER_ID.
Custom parameters	Optional Up to 27 custom parameters may be included in purchase events sent to Google Analytics 4.