Configure events for Google Enhanced Conversions

Google Enhanced Conversions improves the accuracy of conversion measurement by sending hashed first-party conversion data to Google using one-way SHA-256 hashing of first-party customer data.

When a customer purchases something from your brand’s website, you likely collect some first-party data from that customer to complete the transaction. For example, a physical address, an email address, a phone number, and a full name.

First-party customer data that is associated with online transactions can be sent to Google Enhanced Conversions, after which it can be used to enhance conversion measurement in Google Ads. For example:

• Track sales and events that happen on a website.

• Track sales that happen from a website.

• Match customers to their Google accounts, which were signed-in to when they engaged with one of your ads.

• Attribute customer engagement with a Google Ads campaign by matching data collected on your website with the signed-in Google accounts that engaged with your ads.

Caution

The values for email and phone sent to Google Enhanced Conversions are SHA-256 hashed automatically by Amperity before sending. Do not use the TO_HEX() function with the email and phone fields for queries that return results for Google Enhanced Conversions.

How this destination works

When a customer sees or clicks a Google ad and later makes a purchase, that purchase does not automatically appear in Google Ads. Google Enhanced Conversions closes that gap by uploading first-party data from Amperity to Google Ads, which then matches the purchase back to the original ad interaction. The method of matching depends on where and how the purchase happened.

Offline web purchases

When a customer clicks a Google ad a gclid (Google Click ID) is captured in the URL at the moment of the click. The customer navigates away and returns the next day to complete a purchase on your website without clicking another ad. Google Ads has no record of that purchase because no conversion tag fired at checkout.

Amperity uploads the purchase with the original gclid attached. Google Ads matches the uploaded conversion back to the click and attributes the purchase to the campaign.

The gclid is the primary match signal for web purchases. Hashed email addresses and hashed phone numbers are optional, but should be included when available to improve match rates when the gclid is stale or unavailable.

Example query

SELECT
  uit.order_id
  ,oe.gclid
  ,uit.order_datetime AS timestamp
  ,mc.email
  ,mc.phone
  ,uit.unit_price
  ,uit.quantity
  ,uit.product_id
  ,'USD' AS currency_code
FROM Unified_Itemized_Transactions uit
JOIN Online_Events oe ON uit.amperity_id = oe.amperity_id
JOIN Merged_Customers mc ON uit.amperity_id = mc.amperity_id
WHERE oe.gclid IS NOT NULL

where the following fields are:

• Required: order_id, gclid, and timestamp.

• Recommended: email, phone, unit_price, quantity, and currency_code

• Optional: product_id, merchant_id, feed_country_code, feed_language_code, local_transaction_cost, ad_personalization, and ad_user_data

• Omit: gbraid, wbraid, and conversion_environment. gbraid and wbraid apply only to “APP” purchases.

Offline app purchases

App purchases use different click identifiers depending on which direction the ad interaction went:

• gbraid The customer clicked a web ad and was directed to your iOS app.

• wbraid The customer clicked an iOS app ad and was directed to a webpage before completing the purchase in-app.

These identifiers work the same way as gclid for matching. Include hashed email and phone as supplementary identifiers.

You may also set conversion_environment to APP to record that the conversion occurred in an app. This field is only available to allowlisted Google Ads accounts. Omit it if your account is not allowlisted.

Example query

SELECT
  uit.order_id
  ,oe.gbraid
  ,oe.wbraid
  ,uit.order_datetime AS timestamp
  ,mc.email
  ,mc.phone
  ,uit.unit_price
  ,uit.quantity
  ,uit.product_id
  ,'USD' AS currency_code
  ,'APP' AS conversion_environment
FROM Unified_Itemized_Transactions uit
JOIN Online_Events oe ON uit.amperity_id = oe.amperity_id
JOIN Merged_Customers mc ON uit.amperity_id = mc.amperity_id
WHERE oe.gbraid IS NOT NULL
   OR oe.wbraid IS NOT NULL

where the following fields are:

• Required: order_id, timestamp, and at least one of gbraid or wbraid

• Recommended: email, phone, unit_price, quantity, and currency_code

• Optional: product_id, merchant_id, ad_personalization, ad_user_data, and conversion_environment.

• Omit: gclid

In-store purchases

A customer sees a Google ad, does not click it, and later walks into a physical store to make a purchase. There is no click ID of any kind. The only link between the purchase and the ad is the customer’s identity.

Amperity uploads the transaction with hashed email and phone. Google Ads matches those values against the signed-in Google accounts that previously engaged with your ads. If the customer’s email or phone on file with you matches their Google account, the purchase is attributed to the campaign.

Email and phone are both required for in-store attribution. Without at least one of them, Google has nothing to match against. Include both whenever your point-of-sale system captures them — each additional identifier improves the chance of a successful match. Amperity SHA-256 hashes email and phone automatically before upload.

conversion_environment does not apply to in-store purchases. Neither APP nor WEB is accurate for a store transaction. Omit it.

Example query

SELECT
  uit.order_id
  ,uit.order_datetime AS timestamp
  ,mc.email
  ,mc.phone
  ,uit.unit_price
  ,uit.quantity
  ,uit.product_id
  ,'USD' AS currency_code
FROM Unified_Itemized_Transactions uit
JOIN Merged_Customers mc ON uit.amperity_id = mc.amperity_id
WHERE mc.email IS NOT NULL
   OR mc.phone IS NOT NULL

where the following fields are:

• Required: order_id, timestamp, and at least one of email or phone

• Recommended: email, phone, unit_price, quantity, and currency_code

  Important

  Rows where both email and phone are NULL are dropped before upload. They cannot be matched and are silently excluded. Filter them out in your query, as shown above, to keep row counts accurate.

• Optional: product_id, merchant_id, feed_country_code, feed_language_code, local_transaction_cost, ad_personalization, and ad_user_data

• Omit: gclid, gbraid, wbraid, and conversion_environment.

Multiple purchase channels in the same query

If your events data consolidates web, app, and in-store purchases into a single events table, you can send all three to Google Enhanced Conversions in one query. Each row must include at least one match signal–gclid, gbraid, or wbraid–or a customer identifier–email or phone. Fields that do not apply to a given channel are NULL. The connector sends only the fields that are present and drops rows where no match signal exists.

SELECT
  events.order_id
  ,events.event_datetime AS timestamp
  ,events.gclid
  ,events.gbraid
  ,events.wbraid
  ,mc.email
  ,mc.phone
  ,uit.unit_price
  ,uit.quantity
  ,uit.product_id
  ,'USD' AS currency_code
  ,events.conversion_environment
FROM Customer_Events events
JOIN Unified_Itemized_Transactions uit ON events.order_id = uit.order_id
LEFT JOIN Merged_Customers mc ON events.amperity_id = mc.amperity_id
WHERE events.gclid IS NOT NULL
   OR events.gbraid IS NOT NULL
   OR events.wbraid IS NOT NULL
   OR mc.email IS NOT NULL
   OR mc.phone IS NOT NULL

The source table must have values that map correctly across all three purchase channels:

1. gclid is set for web purchases. It is NULL for app and in-store purchases.

2. gbraid is set when a customer clicked a web ad and was directed to your iOS app. It is NULL for web and in-store purchases.

3. wbraid is set when a customer clicked an iOS app ad and was directed to a webpage. It is NULL for web and in-store purchases.

4. email and phone are the primary match signals for in-store purchases, and supplement click IDs for web and app purchases. Amperity hashes both automatically before upload. Do not hash them in the query.

5. conversion_environment should be “WEB” or “APP” when known. Set to NULL for in-store purchases. This field is only available to allowlisted Google Ads accounts; omit conversion_environment if your account is not allowlisted.

6. The WHERE clause ensures every row has at least one match signal. Rows that do not satisfy this condition are dropped by the connector before upload.

Optional. In-store, physical addresses

For retailers with large in-store transaction volumes, Google offers a separate program called Store Sales that supports physical address as a match identifier. This is useful when customers have provided a mailing address but not an email or phone number.

Store Sales is a distinct Google Ads program from Enhanced Conversions. It requires allowlisting by Google and has minimum volume thresholds: at least 30,000 in-store transactions and 500,000 ad interactions within the previous 90 days. If your account does not meet these thresholds, use the in-store purchases approach described above instead.

When using Store Sales, Amperity exports a formatted CSV file via SFTP, which is then uploaded to Google Ads through the UI or API. The CSV file uses a two-row header structure required by Google:

• The first row contains metadata, such as timezone, loyalty rate, or transaction upload rate.

• The second row contains column names. Google hashes PII automatically on upload, or you can pre-hash using SHA-256.

Identifiers supported by Store Sales

Store Sales supports more identifiers per customer than the Enhanced Conversions API path:

• Email addresses: up to 3 per customer

• Phone numbers: up to 3 per customer. Phone numbers must be in E.164 format

• Physical address, including first name, last name, street, city, state, postal code, and country

Include as many identifiers as your data contains. Each additional identifier helps improve match rates.

When to use this instead of the in-store API path

Use Store Sales instead of in-store purchases when:

• Your account is allowlisted for the Store Sales program.

• You have customers whose physical address is known, but email and phone are not. Those customers cannot be matched using Google Enhanced Conversions.

• Your in-store transaction volume exceeds program thresholds.

Use the in-store API path for purchases when:

• Your account is not enrolled in Store Sales.

• Your customers reliably provide email or phone at checkout.

• You want a single automated pipeline that handles web, app, and in-store conversions.

Get details

Review the following details before configuring credentials for Google Enhanced Conversions and before configuring Amperity to send events to Google Enhanced Conversions.

	Configure Google Ads Enable enhanced conversions for leads in Google Ads: Enable conversion tracking in Google Ads . Accept customer data terms and opt-in to enhanced conversions for leads. Set up tagging through Google Tag Manager. Create at least one ConversionAction. The conversion_action_type must be set to UPLOAD_CLICKS. Note Amperity will automatically create a ConversionAction with the name you provide if one does not already exist in Google Ads. Configure Google tag settings to enable enhanced conversions for leads.
	Events data Load to Amperity data that tracks events data for carts, items in carts, and customer consent. This dataset should include the Google Ads click ID. Some of this data may be sent to Google Enhanced Conversions for customer attribution.
	Credential settings Refresh token A refresh token is generated by the OAuth process and authorizes Amperity to send data to Google Enhanced Conversions. The value for the refresh token is automatically updated. Important Authentication for “Google Enhanced Conversions” must be completed within Google prior to configuring Amperity to send ads to Google Enhanced Conversions.
	Required configuration settings Customer ID The Customer ID of the Google Enhanced Conversions account.

Configure credentials

Configure credentials for Google Enhanced Conversions before adding a destination.

An individual with access to Google Enhanced Conversions should use SnapPass to securely share “Customer ID” details with the individual who configures Amperity.

To configure OAuth

	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 Enhanced Conversions. 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-ads” credential type, configure settings, and then click Save. Refresh token A refresh token is generated by the OAuth process and authorizes Amperity to send data to Google Enhanced Conversions. The value for the refresh token is automatically updated.

Add destination

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

To add a destination for Google Enhanced Conversions

	Open the Destinations page, select the New destinations button, and then select Orchestration. To configure a destination for Google Enhanced Conversions, do one of the following: Click the row in which Google Enhanced Conversions is located. Destinations list alphabetically and you can scroll up and down the list. Search for Google Enhanced Conversions. Start typing “google”. The list filters to show only matching destinations. Select “Google Enhanced Conversions”.
	Select the credential for Google Enhanced Conversions from the Credential dropdown, and then click Continue. Tip If there are any issues with destination connectivity, an error message will display in the destination setup dialog. If the destination saves successfully, the connection is ready for use.
	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”. Conversion action name (Required at orchestration) The name of the conversion action. Customer ID Required The Customer ID of the Google Enhanced Conversions account.
	After configuring this destination users may use orchestrations to send query results Google Enhanced Conversions.
	Test the connection with Google Enhanced Conversions by using an audience with a very small membership. For example: 10 or 100 members or the minimum audience size recommended by Google Enhanced Conversions. Send the test audience to Google Enhanced Conversions and verify the audience is correct in Google Enhanced Conversions. Make adjustments if necessary. Only send full audiences after validation is complete.

Fields for enhanced conversions

Fields for enhanced conversions must include hashed customer profile data–email addresses and phone numbers–and should include a transaction identifier and the Google Ads click ID.

The following table describes the fields that may be sent to Google Enhanced Conversions for customer attribution. You should send as many of these fields as you can for each potential attribution to customer activity.

Important

The order_id field is required. Each conversion must also include at least one of: gclid, gbraid, wbraid, email, or phone. Rows that do not meet these requirements are dropped before upload. When a batch is uploaded, row-level failures do not fail the entire batch (partialFailure is enabled). Each conversion supports a maximum of five user identifiers (email and phone combined).

Amperity	Google	Description
Varies.	ad_personalization	The customer consent status for personalization for Google Ads. Note This field should be in the table that contains online events data for websites and mobile apps collected by Google Ads, but may be located in a table for consent tracking.
Varies.	ad_user_data	The customer consent status for Google Ads. Note This field should be in the table that contains online events data for websites and mobile apps collected by Google Ads, but may be located in a table for consent tracking.
Varies.	conversion_environment	The environment in which the conversion occurred. Valid values are APP or WEB. Note This field is only available to allowlisted customers. UNSPECIFIED and UNKNOWN are API-internal values and cannot be set by users. Note This field should be in the table that contains online events data for websites and mobile apps collected by Google Ads.
Varies.	currency_code	The currency code for the conversion_value.
Email	email	The email address for the customer. Amperity automatically normalizes email addresses by converting to lowercase, trimming spaces, removing dots from Gmail addresses, and then using SHA-256 to hash the value before uploading to Google Enhanced Conversions. Tip Use the email field in the Merged Customers table.
Varies.	feed_language_code	The language code used in Google services to set the language of an advertising feed.
Varies.	feed_country_code	The country code used in Google services to set the language of an advertising feed.
Varies.	gbraid	A gbraid is a URL parameter present when a user clicks on an ad on the web, and then is directed to your brand’s iOS app. Note This field should be in the table that contains online events data for websites and mobile apps collected by Google Ads.
Varies.	gclid	A gclid is an identifier captured from URL parameters when a customer clicks on an ad, and then navigates to your brand’s website. This is the best identifier for online events and Google Ads. Important Send all relevant data for a conversion even if the gclid is unavailable. Conversions data that only includes user-provided data is still useful. Note This field should be in the table that contains online events data for websites and mobile apps collected by Google Ads.
Item Cost	local_transaction_cost	The individual cost for each item in the order. Tip Use the Item Cost field in the Unified Itemized Transactions table.
Store ID	merchant_id	A store ID is a unique identifier for the location of a store. Tip Use the Store ID field in the Unified Itemized Transactions table.
Order ID	order_id	An order ID is the unique identifier for the order. It links together all items in the same transaction. For returns and cancellations, the order ID is the unique identifier for the original order, including returned or canceled items. Google Enhanced Conversions refers to this as the transaction ID for the conversion. This field is required. Important Order IDs must be unique per conversion action. Duplicate order IDs within the same conversion action are silently ignored by Google Ads. Tip Use the Order ID field in the Unified Itemized Transactions table.
Phone	phone	The phone number for the customer. Amperity automatically normalizes phone numbers by converting to E.164 format, and then using SHA-256 to hash the value before uploading to Google Enhanced Conversions. Tip Use the phone field in the Merged Customers table.
Product ID	product_id	The unique identifier for a product. Tip Use the Product ID field in the Unified Itemized Transactions table.
Item Quantity	quantity	Item quantity is the total number of items in an order. For returned and canceled items, item quantity is the total number of returned or canceled items. Tip Use the Item Quantity field in the Unified Itemized Transactions table.
Varies.	timestamp	The date and time of the conversion. The value must have a timezone and the format must be yyyy-mm-dd hh:mm:ss+|-hh:mm. Daylight Savings Time (DST) may be ignored. Note This field should be in the table that contains online events data for websites and mobile apps collected by Google Ads or it may be the Order Datetime field in the Unified Itemized Transactions table.
Unit List Price	unit_price	Unit list price is the manufacturer’s suggested retail price (MSRP) for a single unit of an item. Note Amperity calculates the conversion value sent to Google Enhanced Conversions as SUM(unit_price * quantity) aggregated by order ID. This value is not a directly configurable field. Tip Use the Unit List Price field in the Unified Itemized Transactions table.
Varies.	wbraid	A wbraid is a URL parameter that is present when a user clicks on an ad in an iOS app and is directed to a webpage. Note This field should be in the table that contains online events data for websites and mobile apps collected by Google Ads.

Google Ads API reference

Amperity uses the Google Ads API v24 to send data to Google Enhanced Conversions. The following services are called:

• GoogleAdsService.SearchStream — used to retrieve conversion tracking settings and look up existing conversion actions.

• ConversionUploadService.UploadClickConversions — used to upload click conversions. Batches are capped at 2,000 rows.

• ConversionActionService.MutateConversionActions — used to create a conversion action when one with the configured name does not already exist.