How to use Google Ads API to upload offline conversion

Offline conversions are essential for business that convert their customers offline. E.g. Car businesses, usually a test drive sign up is done on the website then head down to the showroom for the test drive and purchase. Or a smaller business such as hair salon/nail parlor/insurance agent, digital marketing could just be the first step.

If we want to optimize towards CPA or ROAS, ability to upload back these offline conversion is important to signal to the ads campaigns on how to optimize.

Google offers a few ways to upload offline leads:

1. Enhance conversion for leads. I will talk about this in another article
2. Offline upload manually. Collecting all the users’ click ID and upload them manually in the UI. I will talk about this in another article
3. Offline upload using Google Ads API. This is the most automated way but technically more advance.

Let’s start with the requirements:

• A Google Ads API account with appropriate permissions. Set up your config file using this guide.
• A Google Ads conversion action set up for offline conversions.
• Stored click identifiers (e.g. gclid) from clicked ads.
• A development environment for API calls (using a client library or REST). For this guide, we will use Python as the scripting language.

Let’s kick-start the process!

1. Install the environment library. For this guide, we use python. So install Google Ads Python library.

pip install google-ads

2. Open up google-ads-python/google-ads.yaml

Fill up the config file(Google-ads.yaml). If you need help, look at this guide.

3. Create offline conversion in Google Ads

• Go to the conversion page in Google Ads
• Select Create New
• Select Manual import using API or uploads.
• Follow the wizard to fill up all the fields.
• Finish the setup and click into the offline conversion event.
• Look at the URL of the conversion action page. Find ctId, this is the conversion ID. Note down the number of your conversion action ID. We need to use this for the API call as part of the data preparation.

4. Data preparation

For this, you will have to capture the click identifiers on your website first. Each click from Google Ads create a click identifier(gclid) and get appended in the click URL, capture this as ID of the data. This will help Google Ads to identify which click is led to a conversion and how much the conversion value cost.

Here is a JavaScript code to capture the gclid:

<script>
function getParam(p) {
var match = RegExp('[?&]' + p + '=([^&]*)').exec(window.location.search);
return match && decodeURIComponent(match[1].replace(/+/g, ' '));
}
getParam('gclid'); // This call the getParam function to extract gclid from the URL
</script>

You should have a data structure of the following:

• Customer ID (This is your account ID, e.g. 123–456–7890, not each user ID)
• Conversion action ID
• Click identifier (gclid)
• Conversion Date Time: The date and time of the conversion (should be after the click time). The format is ‘yyyy-mm-dd hh:mm:ss+|-hh:mm’,
  e.g. ‘2021–01–01 12:32:45+08:00’. The last part “-hh:mm” represent the GMT timezone.
• Conversion value (optional, please include this if you want to optimize towards ROAS)
• Currency code (optional, please include this if you want to optimize towards ROAS)
• Order ID (optional)

5. Create a ClickConversion object and send it to the server using Google Ads Python Library

Here comes the fun part.. Let’s get our hands dirty with some codes.

import google.ads.googleads.client as client
## This create a function to upload the click conversion
def upload_click_conversion(customer_id, conversion_action_id, gclid, conversion_time, conversion_value):
    # GoogleAdsClient will read the google-ads.yaml configuration file in the
    # home directory if none is specified.    
    client_config = client.GoogleAdsClient.load_from_storage(version="v15")
    google_ads_client = client.GoogleAdsClient(client_config)
click_conversion = google_ads_service.types.ClickConversion()
    click_conversion.conversion_action = google_ads_client.get_path(
        'conversion_actions', customer_id, conversion_action_id
    )
    click_conversion.gclid = gclid
    click_conversion.conversion_time = conversion_time
    click_conversion.conversion_value = conversion_value
# Add other optional fields like currency_code, order_id, custom variables, if needed.
conversion_upload_service = google_ads_client.get_service("ConversionUploadService")
    request = google_ads_client.get_type("UploadClickConversionsRequest")
    request.customer_id = customer_id
    request.conversions.append(click_conversion)
    request.partial_failure = True   # Handle potential errors gracefully
# Send the request
    response = conversion_upload_service.upload_click_conversions(request=request)
    print(response)
# You should be able to pass in the click conversion details here by reading your file and do a loop.
# Here is an example, you should replace your actual information with a loop reading from your data source
upload_click_conversion("123–456–7890", 123456789, "1234poiuu56789trewqw", "2021–01–01 12:32:45+08:00", 9)