# Google Ads Conversions API Reference

{% hint style="info" %}
The Google Ads Conversion API requires setting up new Conversion Actions within Google Ads. If you want to re-use your existing Google Ads configuration, take a look at the [Google Ads Proxy Destination](https://documentation.freshpaint.io/integrations/destinations/direct-response-ads/google-ads).
{% endhint %}

Optimize your Google Ads spend by attributing ad clicks to conversion and other key behaviors.

## Destination Info

* Supports [Track](https://documentation.freshpaint.io/developer/freshpaint-sdk-reference#track) calls
* Supports [HIPAA mode](https://documentation.freshpaint.io/hipaa-mode)
* Refer to this destination as **Google Ads Conversion API** in the [Integrations object](https://documentation.freshpaint.io/reference/developer/freshpaint-sdk-reference#using-the-integrations-object)
* Connection Modes:

<table><thead><tr><th width="200.33333333333331" align="right"> </th><th data-type="checkbox">Client-side</th><th data-type="checkbox">Server-side</th></tr></thead><tbody><tr><td align="right">Web</td><td>false</td><td>true</td></tr><tr><td align="right">Mobile</td><td>false</td><td>true</td></tr><tr><td align="right">Server</td><td>false</td><td>true</td></tr></tbody></table>

This is a reference document for the Google Ads Conversions API destination. For information on how to set up this integration, see the[ Quick Start guide](https://documentation.freshpaint.io/integrations/destinations/direct-response-ads/google-ads-conversion-api/google-ads-conversion-api-quick-start-guide).

### Events

Freshpaint `.track()` events map to any **Click Conversions** you've already created in Google Ads.

## Track Events

When you send an event to Google Ads, you can track conversions from your ad campaigns based on those events.

### Server-side

You may provide the following additional event properties:

<table data-header-hidden data-full-width="true"><thead><tr><th width="153"></th><th width="135"></th><th width="87"></th><th width="113"></th><th></th></tr></thead><tbody><tr><td><strong>Freshpaint property</strong></td><td><strong>Google Ads parameter</strong></td><td><strong>Type</strong></td><td><strong>Required?</strong></td><td><strong>Description</strong></td></tr><tr><td><code>$gclid</code> or <code>$gbraid</code> or <code>$wbraid</code></td><td><code>gclid</code> or <code>wbraid</code> or <code>gbraid</code></td><td>string</td><td>Required</td><td>gclid (Google Click ID) is generated at ad click time and appended to the landing page URL. <strong>Freshpaint will automatically capture gclid for events from your website</strong>. If you wish, you may provide <code>$gclid</code> as an event property to override the automatically captured value. <code>wbraid</code> or <code>gbraid</code> can be used instead of <code>gclid</code>.</td></tr><tr><td><code>ctname or ctid</code></td><td><code>ctid</code></td><td>string</td><td>Required</td><td>The Conversion Name or Conversion Id of the conversion action in Google Ads. When using the Conversion Name, the Freshpaint integration will lookup the conversion id before sending the event to google. When using the Conversion Id, the name of the Freshpaint Event must exactly match the name of the Google Ads Conversion name.</td></tr><tr><td><code>time</code></td><td><code>conversionDateTime</code></td><td>number</td><td>Optional</td><td>The time the event occurred as a unix epoch. The time needs to be after the ad is clicked or it won't be accepted by google.</td></tr><tr><td><code>cart_data</code></td><td><code>cartData</code></td><td>object</td><td>Optional</td><td>The cart data associated with this conversion. <a href="https://developers.google.com/google-ads/api/reference/rpc/v23/CartData">Google Docs</a></td></tr><tr><td><code>external_attribution_data</code></td><td><code>externalAttributionData</code></td><td>list</td><td>Optional</td><td>Additional data about externally attributed conversions. This field is required for conversions with an externally attributed conversion action, but should not be set otherwise. <a href="https://developers.google.com/google-ads/api/rest/reference/rest/v13/customers/uploadClickConversions#ExternalAttributionData">Google Docs</a></td></tr><tr><td><code>custom_variables</code></td><td><code>customVariables</code></td><td>list</td><td>Optional</td><td>The custom variables associated with this conversion. <a href="https://developers.google.com/google-ads/api/rest/reference/rest/v13/CustomVariable">Google Docs</a></td></tr><tr><td><code>conversion_environment</code></td><td><code>conversionEnvironment</code></td><td>enum</td><td>Optional</td><td>The environment this conversion was recorded on, for example, App or Web. <a href="https://developers.google.com/google-ads/api/rest/reference/rest/v13/customers/uploadClickConversions#ConversionEnvironment">Google Docs</a></td></tr><tr><td><code>value</code> or <code>total</code> or <code>revenue</code></td><td><code>value</code></td><td>number</td><td>Optional</td><td>Value of the conversion. See <a href="https://support.google.com/google-ads/answer/3419241?hl=en#zippy=%2Cmeasure-transaction-specific-conversion-values%2Cconversion-value-currency">About conversion values</a> for more information</td></tr><tr><td><code>currency</code></td><td><code>currency_code</code></td><td>string</td><td>Optional</td><td>Currency of the conversion value, "USD" by default. See the list of <a href="https://support.google.com/merchants/answer/160637?hl=en">supported currency codes</a>.</td></tr><tr><td><code>email</code></td><td><code>email</code></td><td>string</td><td>Optional</td><td>The email address of the user</td></tr><tr><td><code>phone</code> or <code>phone_number</code></td><td><code>phone</code></td><td>string</td><td>Optional</td><td>The phone number of the user</td></tr><tr><td><code>mobile_id</code></td><td><code>mobileID</code></td><td>string</td><td>Optional</td><td>Mobile device ID (advertising ID/IDFA). Accepted only for Customer Match.</td></tr><tr><td><code>third_party_user_id</code></td><td><code>thirdPartyUserID</code></td><td>string</td><td>Optional</td><td>Advertiser-assigned user ID for Customer Match upload, or third-party-assigned user ID for Store Sales. Accepted only for Customer Match and Store Sales.</td></tr><tr><td><code>address_info</code></td><td><code>offlineAddressInfo</code></td><td>object</td><td>Optional</td><td>Address information. Accepted only for Customer Match, Store Sales, and ConversionAdjustmentUploadService. <a href="https://developers.google.com/google-ads/api/rest/reference/rest/v13/UserIdentifier#OfflineUserAddressInfo">Google Docs</a></td></tr><tr><td><code>order_id</code></td><td><code>orderID</code></td><td>string</td><td>Optional</td><td>The order ID associated with the conversion. An order id can only be used for one conversion per conversion action. Used to avoid duplicate conversions in Google Ads. </td></tr></tbody></table>

{% hint style="info" %}
Freshpaint will only deliver events to Google when a user arrives on your site by clicking on a Google Ad, thus generating an `gclid`. Without `gclid`, Google will not be able to attribute conversions.
{% endhint %}

## Setup Conversion Actions

Please refer to the [Quick Start Guide](https://documentation.freshpaint.io/integrations/destinations/direct-response-ads/google-ads-conversion-api-quick-start-guide#next-youll-need-to-setup-conversion-actions-in-google-a-ds-and-link-your-freshpaint-event-to-your-go) for instructions on how to set up conversion actions.

## Misc. Considerations

* Conversions may take up to 24 hours to appear in your Google Ads Conversion Goals.
* [Google Ads API v15 introduces a consent object](https://support.google.com/google-ads/answer/14546648?hl=en) to indicate whether users within the European Economic Area have consented to the event being shared with Google. If the event is enabled and consented to within Freshpaint using the Freshpaint consent management features, Freshpaint will automatically mark the event as consented to when sending the event to Google's servers. See [Consent Management](https://documentation.freshpaint.io/integrations/consent-management) for more information.

## Conversion Event Imports Between Google Analytics and Google Ads&#x20;

The workflow of importing GA4 events as conversion actions in Google Ads is considered non-compliant, primarily related to the handling of user identifiers like the GCLID (Google Click Identifier).&#x20;

To remain compliant for both GA4 and Google Ads, Freshpaint recommends:&#x20;

* **Not allowlisting the Google Click Identifier (GCLID) property for your Google Analytics destination.**&#x20;
* **Creation of net-new Website Conversion Actions in Google Ads:** Instead of passing the GCLID directly to GA4, create specific Website conversion actions. The conversion action name can be used as the "ctname" property, along with a "conversion label" property which allows Freshpaint to map an event to a specific conversion action in Google Ads.&#x20;
* **Unlinking your Google Analytics 4 property from your Google Ads account:** The process for how these 2 tools are unlinked is documented [here](https://support.google.com/analytics/answer/9379420), under the "Unlinking Google Ads accounts from Analytics" section of the article.

## Authentication

Freshpaint supports using either a User Account or Service Account for accessing the Google Ads Conversion API.

#### User Account

A user who has access to both Freshpaint and Google Campaign Manager 360 may delegate access to Freshpaint using the user account. Freshpaint will be granted the limited permissions necessary to send conversion events to google CM360 and be directly tied to the account of the user who delegated access. If that user account is removed or reset, google may revoke the authentication credentials that have been delegated to Freshpaint under that user account.

{% hint style="info" %}
The user delegating access to their User Account needs to have the "Insert offline conversions" permission as part of their role within Campaign Manager 360.
{% endhint %}

Navigate to the destination configuration page and click either `Connect` or `Reconnect` in the `Access Permission` row of the destination configuration page. In the popup dialog select User Account and then `Connect with Google CM360` which will redirect you to Google to complete setting up authentication between Freshpaint and Google services.

<figure><img src="https://1666823438-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MA7aDqsXMFbUsWVqonF%2Fuploads%2FP7GKeDHRiKka3V5V8iUl%2Fimage.png?alt=media&#x26;token=fb9fb76d-9c86-46de-82ec-2685873c0ade" alt=""><figcaption></figcaption></figure>

#### Service Account

An account within google can be created only for Freshpaint that will provide Freshpaint with a set of credentials for Freshpaint to use when sending conversion events to Google. The creation of this account will require necessary permissions to the underlying google account.

Please follow the Google documentation on the creation and configuration of a service account available at: <https://developers.google.com/google-ads/api/docs/oauth/service-accounts>

{% hint style="info" %}
The service account should be provided with the <https://www.googleapis.com/auth/adwords>scope which will allow access to send conversion events to Google.
{% endhint %}

Once the service account has been created within Google, the credentials file can be uploaded to the Freshpaint application.

Navigate to the destination configuration page and click either `Connect` or `Reconnect` in the `Access Permission` row. In the popup dialog select `Service Account` and upload the json file that google provided with the credentials for Freshpaint.

## View-Through Conversions and Retargeting

Freshpaint does not currently support view-through conversions. We only support click-based conversions that include a `gclid`, `gbraid`, or `wbraid` parameter.

Note that retargeting of anonymous users is not possible due to the absence of an identifier that can be used to retarget that user.