Google Ads

Tracking and Importing Conversions  |  AdWords API  |  Google Developers

A conversion in Google Ads is when a user performs some specified action after
clicking an ad or viewing a Display Network ad, such as purchasing a product,
installing a mobile app, or signing up for an email list.

Conversion tracking provides key
insights into users’ actions after viewing or clicking an ad. You can keep
track of users who call, buy a product, install a mobile app, and more. Google
Ads provides different conversion trackers for the different ways customers convert.

This guide describes the different types of conversion trackers and how to
apply them. It also describes how to use the API to import offline conversions
into Google Ads.

Types of conversion trackers

To measure conversions, you set up a
ConversionTracker
for the type of conversion actions you want to track. For instance,
an online purchase and a phone call require different conversion trackers.

Most conversion types also require additional actions on your part to track
them. For instance, tracking conversion actions on your website requires
creation of an
AdWordsConversionTracker
and a code snippet called a tag that you add to the conversion page on your
website.

Note that conversion sources related to calls in the Google Ads UI (Phone
number clicks
, Calls from ads, and Calls from websites) are each
mapped to a different ConversionTracker in the AdWords API:

The following sections describe the different types of conversion trackers.

Conversions on websites

The
AdWordsConversionTracker
encompasses several types of website conversions, distinguished within the API
by the trackingCodeType field.

The table below shows the equivalent API parameters to use for each Source
in the Google Ads UI:

trackingCodeType Google Ads UI Source
WEBPAGE Website
WEBPAGE_ONCLICK Website
CLICK_TO_CALL Phone number clicks
Analytics

Website and Phone number clicks conversions require the
googleEventSnippet,
which should be placed on web pages that indicate a conversion action such as a
checkout confirmation or lead submission page,
and googleGlobalSiteTag,
which must be installed on every page of your website. You can retrieve both of
these attributes with
ConversionTrackerService.

The CLICK_TO_CALL type differs from
AdCallMetricsConversion
in that it does not track actual phone calls. Instead, it tracks only clicks on
a phone number from a mobile device. This is useful when you’re unable to use a
Google forwarding number for tracking actual phone calls.

Phone call conversions

Tracking phone calls from call extensions requires an
AdCallMetricsConversion
tracker. These use a Google forwarding
number
and specify the conversion
tracker in the phone call extension’s FeedItem. In the Google Ads UI, this type
of conversion is called Calls from ads.

You track this conversion type by specifying the tracker in the phone call
extension’s
FeedItem using
the placeholder type for
CONVERSION TYPE ID.

A call is reported as a conversion if it lasts longer than a specified
duration. The default is 60 seconds.

App conversions

An
AppConversion
covers both mobile app installs and in-app actions, for Android and iOS. The
table below shows the equivalent API parameters to use for each Source in
the Google Ads UI:

appPlatform appConversionType Google Ads UI Source
ITUNES FIRST_OPEN iOS app install (first open)
ITUNES IN_APP_PURCHASE iOS in-app action
ANDROID_MARKET DOWNLOAD Android app install (from Google Play)
ANDROID_MARKET FIRST_OPEN Android app install (first open)
ANDROID_MARKET IN_APP_PURCHASE Android in-app action

When you specify FIRST_OPEN as the appConversionType, you can provide an
appPostbackUrl
to get instant confirmation when a user first opens your app. See the Android
mobile app conversion tracking
guide
for more details.

Upload click conversions

An
UploadConversion
maps to the Import conversion source in the Google Ads UI followed
by Conversion from clicks. When they’re created in the web interface,
auto-tagging is automatically
enabled for the account, but this does not occur when you create the
conversion tracker via the API. If you create a conversion tracker using the
API, you should enable auto-tagging using
CustomerService.
Without auto-tagging you won’t get the GCLID parameter required to upload
conversions corresponding to a click.

Once you create an
UploadConversion,
you can use the
OfflineConversionFeedService
to upload conversions for clicks. See Importing Click
Conversions
below for details.

Upload call conversions

An
UploadCallConversion
maps to the Import conversion source in the Google Ads UI followed
by choosing Conversion from calls.

A mobile click-to-call click cannot be uploaded as a conversion if there is no
Google forwarding number attached to the call. Without a Google forwarding
number, there is no way Google can be sure that the click led to a call and
then to a conversion. If a click is uploaded like this, it will be ignored by
the conversion tracker.

Once you create an
UploadCallConversion,
you can use the
OfflineCallConversionFeedService
to upload conversions for calls. See Importing Call
Conversions
below for details.

Calls from websites

A
WebsiteCallMetricsConversion
maps to Calls from a website in
the Google Ads UI.

Unlike
AdCallMetricsConversion,
this tracker requires googleEventSnippet
and googleGlobalSiteTag
to be added to your website to retrieve the dynamic Google forwarding number for
call tracking on numbers listed on your website. In addition, you must set up a
call extension and attach it to
the campaign or ad groups whose website calls you want to track.

Store Sales Direct conversions

Store Sales Direct Uploads allows you to import offline transactions in Google
Ads either directly or through third-party partners. By matching transaction data
from your point-of-sale systems or customer database, you can see how your
Google ads translate into offline purchases. The offline transactions can be
uploaded in an OfflineDataUpload object
through the OfflineDataUploadService.

System-wide default conversion trackers

Google Ads provides some system-wide default conversion trackers that don’t
require tags. These trackers have default settings for various fields including
name, value, etc.

If you want to edit the settings for these default conversion trackers, you
must do so through the Google Ads UI. If you try to edit these kinds of conversion
trackers in the API, the API will throw an INVALID_ORIGINAL_CONVERSION_TYPE_ID
error.

Cross-account conversion tracking

If you’re using cross-account conversion
tracking
, the
ConversionTrackerService
returns the following conversion types:

  1. All conversion types defined by the manager account used by the account for
    cross-account conversion tracking.
  2. All conversion types on which the customer has accrued stats, including
    system-defined types, and types owned by the manager even if that manager
    unlinks subsequently.
  3. All types the customer has defined in their own account, including Analytics
    goals and transactions created in linked Google Analytics profiles. This
    includes types not imported into Google Ads, which will have a status of
    HIDDEN
    and can only be imported using the Google Ads UI.

You can set up and query cross-account conversion trackers via the API, but you
must opt in your accounts to cross-account conversion tracking from the manager
account. See this help center
article
for more information.

In the past, the Conversions column contained only those conversions that
occurred on the same device. Now you can choose to include cross-device
conversions in the Conversions column using the
optimizeOnEstimatedConversions
property of the customer’s conversion tracking
settings
.
These conversions will then be used by various automated bid strategies that
optimize for conversions, such as target cost per acquisition (CPA), target
return on ad spend (ROAS), or enhanced cost per click (ECPC).

Conversion fields available in reporting

You can retrieve conversion stats for your accounts, campaigns, or ad groups
using conversion fields available in reports.

The tables below lists some commonly used report fields related to conversions.

Conversions and its derivative fields

AllConversions and its derivative fields

Field Name Description
AllConversions Includes all conversions from Google Ads, regardless of the values of excludeFromBidding. All conversion sources (website, cross-device, phone calls, etc.) contribute to the count.
AllConversionRate AllConversions divided by total clicks that can be conversion-tracked. This is how often, on average, an ad interaction leads to a conversion.
AllConversionValue The total value of all of your conversions. Includes website, cross-device, phone call conversions and conversion actions (ConversionTracker) regardless of the values of excludeFromBidding.
CostPerAllConversion Total cost divided by AllConversions.
ValuePerAllConversion AllConversionValue divided by AllConversions.

CrossDeviceConversions

Field Name Description
CrossDeviceConversions Conversions in which a customer interacts with an ad (for example, by clicking a text ad or viewing a video ad) on one device, then converts on a different device or browser. CrossDeviceConversions is already included in the AllConversions field.

Current Model columns associated with Conversions

When you change the
attributionModelType
field for a conversion action in Google Ads, it only changes the way your
conversions are counted in your Conversions and All conversions columns going
forward. If you want to see how your historic conversions data would look with
the attribution model you’ve just selected, you can use the Current Model
columns listed below. By comparing these columns with the regular conversion
tracking columns, you can see how your data would have differed if you had been
using the current attribution model.

Conversion attribution in reports

The date of a conversion and the date on which you uploaded a conversion have
no impact on the date on which reports will reflect the conversion and its
values. All metrics in reports are attributed to the impression date of each
click
.

For example, let’s say that on October 21, 2017 you upload the following conversions,
all with a conversionTime where the
date portion
is 20171020:

ImpressionDate Conversions ConversionValue
October 18, 2017 500 $1,000
October 19, 2017 250 $200
October 20, 2017 100 $150

In that case, the Conversions and ConversionValues for a report for
October 20, 2017 will only change by 100 and $150, respectively. To see the
changes in Conversions and ConversionValues for all of the uploaded
conversions, you would have to expand the report date range to cover
October 18, 2017 through October 20, 2017.

Similarly, the Conversions and ConversionValue metrics for October 21, 2017
(the date on which you uploaded the conversions) will not change as a result
of the upload.

Importing click conversions

You can use the AdWords API to upload offline
conversions
into Google Ads, giving
you more flexibility in associating clicks with conversions. You can track ads
that led to sales in the offline world, such as over the phone or via a sales
rep.

This section describes how to use the AdWords API to construct a feed for
importing your offline conversions.

Setup

The first step is to create import conversion types. This must be done for each
unique conversion “classification”. You can create them using the Google Ads
UI
or through code:

Java

// Create an upload conversion for offline conversion imports.
UploadConversion uploadConversion = new UploadConversion();
// Set an appropriate category. This field is optional, and will be set to
// DEFAULT if not mentioned.
uploadConversion.setCategory(ConversionTrackerCategory.LEAD);
uploadConversion.setName("Upload Conversion #" + System.currentTimeMillis());
uploadConversion.setViewthroughLookbackWindow(30);
uploadConversion.setCtcLookbackWindow(90);

// Optional: Set the default currency code to use for conversions
// that do not specify a conversion currency. This must be an ISO 4217
// 3-character currency code such as "EUR" or "USD".
// If this field is not set on this UploadConversion, AdWords will use
// the account's currency.
uploadConversion.setDefaultRevenueCurrencyCode("EUR");

// Optional: Set the default revenue value to use for conversions
// that do not specify a conversion value. Note that this value
// should NOT be in micros.
uploadConversion.setDefaultRevenueValue(2.50);
// Optional: To upload fractional conversion credits, mark the upload conversion
// as externally attributed. See
// https://developers.google.com/adwords/api/docs/guides/conversion-tracking#importing_externally_attributed_conversions
// to learn more about importing externally attributed conversions.

// uploadConversion.setIsExternallyAttributed(true);

conversionTrackers.add(uploadConversion);

PHP

// Create an upload conversion for offline conversion imports.
$uploadConversion = new UploadConversion();
// Set an appropriate category. This field is optional, and will be set to
// DEFAULT if not mentioned.
$uploadConversion->setCategory(ConversionTrackerCategory::LEAD);
$uploadConversion->setName('Upload Conversion # ' . uniqid());
$uploadConversion->setViewthroughLookbackWindow(30);
$uploadConversion->setCtcLookbackWindow(90);

// Optional: Set the default currency code to use for conversions
// that do not specify a conversion currency. This must be an ISO 4217
// 3-character currency code such as "EUR" or "USD".
// If this field is not set on this UploadConversion, AdWords will use
// the account's currency.
$uploadConversion->setDefaultRevenueCurrencyCode('EUR');

// Optional: Set the default revenue value to use for conversions
// that do not specify a conversion value. Note that this value
// should NOT be in micros.
$uploadConversion->setDefaultRevenueValue(2.50);

// Optional: To upload fractional conversion credits, mark the upload
// conversion as externally attributed. See
// https://developers.google.com/adwords/api/docs/guides/conversion-tracking#importing_externally_attributed_conversions
// to learn more about importing externally attributed conversions.

// uploadConversion->setIsExternallyAttributed(true);

$conversionTrackers[] = $uploadConversion;

Python

upload_conversion = {
    'xsi_type': 'UploadConversion',
    'name': 'Upload Conversion #%s' % uuid.uuid4(),
    # Optional fields.
    # Set an appropriate category. This will be set to DEFAULT if not
    # specified.
    'category': 'LEAD',
    'viewthroughLookbackWindow': '30',
    'ctcLookbackWindow': '90',
    # Set the default currency code to use for conversions that do
    # not specify a conversion currency. This must be an ISO 4217 3-character
    # code such as "EUR" or "USD".
    # If this field is not set, AdWords will use the account's currency.
    'defaultRevenueCurrencyCode': 'EUR',
    # Set the default revenue value to use for conversions that do not specify
    # a converison value. Note that this value should NOT be in micros.
    'defaultRevenueValue': '2.50',
    # To upload fractional conversion credits, mark the upload conversion as
    # externally attributed. To learn more about importing externally
    # attributed conversions, see:
    # https://developers.google.com/adwords/api/docs/guides/conversion-tracking#importing_externally_attributed_conversions
    # 'isExternallyAttributed': 'true'
}

Ruby

# Prepare for adding upload conversion tracker.
operation2 = {
  :operator => 'ADD',
  :operand => {
    # The 'xsi_type' field allows you to specify the xsi:type of the object
    # being created. It's only necessary when you must provide an explicit
    # type that the client library can't infer.
    :xsi_type => 'UploadConversion',

    # Set an appropriate category. This field is optional, and will be set to
    # DEFAULT if not mentioned.
    :category => 'LEAD',
    :name => "Upload Conversion #%d" % (Time.new.to_f * 1000).to_i,
    :viewthrough_lookback_window => 30,
    :ctc_lookback_window => 90,

    # Optional: Set the default currency code to use for conversions that do
    # not specify a conversion currency. This must be an ISO 4217 3-character
    # currency code such as "EUR" or "USD".
    # If this field is not set on this UploadConversion, AdWords will use the
    # account currency.
    :default_revenue_currency_code => 'EUR',

    # Optional: Set the default revenue value to use for conversions that do
    # not specify a conversion value.
    # Note: that this value should NOT be in micros.
    :default_revenue_value => 2.50,

    # Optional: To upload fractional conversion credits, mark the upload
    # conversion as externally attributed. See
    # https://developers.google.com/adwords/api/docs/guides/conversion-tracking#importing_externally_attributed_conversions
    # to learn more about importing externally attributed conversions.
    #:is_externally_attributed => true
  }
}

Perl

# Create an upload conversion for offline conversion imports.
my $upload_conversion_tracker =
  Google::Ads::AdWords::v201809::UploadConversion->new({
    # Set an appropriate category. This field is optional, and will be set to
    # DEFAULT if not mentioned.
    category                             => "LEAD",
    name                                 => "Upload Conversion #" . uniqid(),
    viewthroughLookbackWindow            => 30,
    ctcLookbackWindow                    => 90,
    # Optional: Set the default currency code to use for conversions
    # that do not specify a conversion currency. This must be an ISO 4217
    # 3-character currency code such as "EUR" or "USD".
    # If this field is not set on this UploadConversion, AdWords will use
    # the account's currency.
    defaultRevenueCurrencyCode => "EUR",
    # Optional: Set the default revenue value to use for conversions
    # that do not specify a conversion value. Note that this value
    # should NOT be in micros.
    defaultRevenueValue => 2.50,
    # Optional: To upload fractional conversion credits, mark the upload conversion
    # as externally attributed. See
    # https://developers.google.com/adwords/api/docs/guides/conversion-tracking#importing_externally_attributed_conversions
    # to learn more about importing externally attributed conversions.
    # isExternallyAttributed => true
  });
push @conversion_trackers, $upload_conversion_tracker;

C#

// Create an upload conversion for offline conversion imports.
UploadConversion uploadConversion = new UploadConversion
{
    // Set an appropriate category. This field is optional, and will be set to
    // DEFAULT if not mentioned.
    category = ConversionTrackerCategory.LEAD,
    name = "Upload Conversion #" + ExampleUtilities.GetRandomString(),
    viewthroughLookbackWindow = 30,
    ctcLookbackWindow = 90,

    // Optional: Set the default currency code to use for conversions
    // that do not specify a conversion currency. This must be an ISO 4217
    // 3-character currency code such as "EUR" or "USD".
    // If this field is not set on this UploadConversion, AdWords will use
    // the account's currency.
    defaultRevenueCurrencyCode = "EUR",

    // Optional: Set the default revenue value to use for conversions
    // that do not specify a conversion value. Note that this value
    // should NOT be in micros.
    defaultRevenueValue = 2.50
};

// Optional: To upload fractional conversion credits, mark the upload conversion
// as externally attributed. See
// https://developers.google.com/adwords/api/docs/guides/conversion-tracking#importing_externally_attributed_conversions
// to learn more about importing externally attributed conversions.

// uploadConversion.isExternallyAttributed = true;

conversionTrackers.Add(uploadConversion);

VB

' Create an upload conversion for offline conversion imports.
Dim uploadConversion As New UploadConversion()
' Set an appropriate category. This field is optional, and will be set to
' DEFAULT if not mentioned.
uploadConversion.category = ConversionTrackerCategory.LEAD
uploadConversion.name = "Upload Conversion #" + ExampleUtilities.GetRandomString()
uploadConversion.viewthroughLookbackWindow = 30
uploadConversion.ctcLookbackWindow = 90

' Optional: Set the default currency code to use for conversions
' that do not specify a conversion currency. This must be an ISO 4217
' 3-character currency code such as "EUR" or "USD".
' If this field is not set on this UploadConversion, AdWords will use
' the account's currency.
uploadConversion.defaultRevenueCurrencyCode = "EUR"

' Optional: Set the default revenue value to use for conversions
' that do not specify a conversion value. Note that this value
' should NOT be in micros.
uploadConversion.defaultRevenueValue = 2.5

' Optional: To upload fractional conversion credits, mark the upload conversion
' as externally attributed. See
' https://developers.google.com/adwords/api/docs/guides/conversion-tracking#importing_externally_attributed_conversions
' to learn more about importing externally attributed conversions.

' uploadConversion.isExternallyAttributed = True

conversionTrackers.Add(uploadConversion)

This snippet creates an
UploadConversion
object using the
ConversionTrackerService.
The given conversionName is used to identify this conversion event, and must
be unique.

After creating your import conversion types, you must enable your website and
lead-tracking system to capture and store the GCLID, the unique ID that Google
Ads provides for every impression of a Google ad and is sent to the Google
server when the ad is clicked. You also must enable
auto-tagging so your website
will start receiving the GCLID as a URL parameter. For more details about these
steps, see Tracking Offline
Conversions
.

Uploading offline conversions

Once you’ve created the
UploadConversion
object, you need to associate your offline conversions with it by passing the
GCLID, conversion time (with timezone
ID
), conversion name, and optionally the
conversion value and conversion currency to
OfflineConversionFeedService:

Java

/**
 * Runs the example.
 *
 * @param adWordsServices the services factory.
 * @param session the session.
 * @param conversionName the name of the conversion tracker.
 * @param gClid the GCLID for the conversion.
 * @param conversionTime the date and time of the conversion.
 * @param conversionValue the value of the conversion.
 * @throws ApiException if the API request failed with one or more service errors.
 * @throws RemoteException if the API request failed due to other errors.
 */
public static void runExample(AdWordsServicesInterface adWordsServices, AdWordsSession session,
    String conversionName, String gClid, String conversionTime,
    double conversionValue) throws RemoteException {

  // Get the OfflineConversionFeedService.
  OfflineConversionFeedServiceInterface offlineConversionFeedService =
      adWordsServices.get(session, OfflineConversionFeedServiceInterface.class);

  // Associate offline conversions with the existing named conversion tracker. If this tracker
  // was newly created, it may be a few hours before it can accept conversions.
  OfflineConversionFeed feed = new OfflineConversionFeed();
  feed.setConversionName(conversionName);
  feed.setConversionTime(conversionTime);
  feed.setConversionValue(conversionValue);
  feed.setGoogleClickId(gClid);

  OfflineConversionFeedOperation offlineConversionOperation =
      new OfflineConversionFeedOperation();
  offlineConversionOperation.setOperator(Operator.ADD);
  offlineConversionOperation.setOperand(feed);

  OfflineConversionFeedReturnValue offlineConversionReturnValue = offlineConversionFeedService
      .mutate(new OfflineConversionFeedOperation[] {offlineConversionOperation});

  OfflineConversionFeed newFeed = offlineConversionReturnValue.getValue(0);

  System.out.printf(
      "Uploaded offline conversion value of %.4f for Google Click ID '%s' to '%s'.%n",
      newFeed.getConversionValue(), newFeed.getGoogleClickId(), newFeed.getConversionName());
}

PHP

$offlineConversionService = $adWordsServices->get($session, OfflineConversionFeedService::class);

// Associate offline conversions with the existing named conversion tracker.
// If this tracker was newly created, it may be a few hours before it can
// accept conversions.
$feed = new OfflineConversionFeed();
$feed->setConversionName($conversionName);
$feed->setConversionTime($conversionTime);
$feed->setConversionValue($conversionValue);
$feed->setGoogleClickId($gclid);

// Optional: To upload fractional conversion credits, set the external
// attribution model and credit. To use this feature, your conversion
// tracker should be marked as externally attributed. See
// https://developers.google.com/adwords/api/docs/guides/conversion-tracking#importing_externally_attributed_conversions
// to learn more about importing externally attributed conversions.

// $feed->setExternalAttributionModel('Linear');
// $feed->setExternalAttributionCredit(0.3);

$offlineConversionOperation = new OfflineConversionFeedOperation();
$offlineConversionOperation->setOperator(Operator::ADD);
$offlineConversionOperation->setOperand($feed);
$offlineConversionOperations = [$offlineConversionOperation];

$result = $offlineConversionService->mutate($offlineConversionOperations);

$feed = $result->getValue()[0];
printf(
    "Uploaded offline conversion value of %d for Google Click ID = '%s' to '%s'.n",
    $feed->getConversionValue(),
    $feed->getGoogleClickId(),
    $feed->getConversionName()
);

Python

# Initialize appropriate services.
offline_conversion_feed_service = client.GetService(
    'OfflineConversionFeedService', version='v201809')

# Associate offline conversions with the existing named conversion tracker. If
# this tracker was newly created, it may be a few hours before it can accept
# conversions.
feed = {
    'conversionName': conversion_name,
    'conversionTime': conversion_time,
    'conversionValue': conversion_value,
    'googleClickId': click_id,
    # Optional: To upload fractional conversion credits, set the external
    # attribution model and credit. To use this feature, your conversion
    # tracker should be marked as externally attributed. To learn more about
    # importing externally attributed conversins, see:
    # https://developers.google.com/adwords/api/docs/guides/conversion-tracking#importing_externally_attributed_conversions
    # 'externalAttributionCredit': 0.3,
    # 'externalAttributionModel': 'Linear'
}

offline_conversion_operation = {
    'operator': 'ADD',
    'operand': feed
}

offline_conversion_response = offline_conversion_feed_service.mutate(
    [offline_conversion_operation])
new_feed = offline_conversion_response['value']

print('Uploaded offline conversion value of "%s" for Google Click ID '
      '"%s" to "%s".' % (new_feed['conversionValue'],
                         new_feed['googleClickId'],
                         new_feed['conversionName']))

Ruby

conversion_feed_srv =
    adwords.service(:OfflineConversionFeedService, API_VERSION)

# Associate offline conversions with the existing named conversion tracker. If
# this tracker was newly created, it may be a few hours before it can accept
# conversions.
feed = {
  :conversion_name => conversion_name,
  :google_click_id => google_click_id,
  :conversion_time => conversion_time,
  :conversion_value => conversion_value
}

# Optional: To upload fractional conversion credits, set the external
# attribution model and credit. To use this feature, your conversion tracker
# should be marked as externally attributed. See
# https://developers.google.com/adwords/api/docs/guides/conversion-tracking#importing_externally_attributed_conversions
# to learn more about importing externally attributed conversions.
#
# feed[:external_attribution_model] = "Linear"
# feed[:external_attribution_credit] = 0.3

return_feeds = conversion_feed_srv.mutate([
  {:operator => 'ADD', :operand => feed}])
return_feeds[:value].each do |return_feed|
  puts ("Uploaded offline conversion value %.2f for Google Click ID '%s', " +
      'to %s') % [return_feed[:conversion_value],
                  return_feed[:google_click_id],
                  return_feed[:conversion_name]]
end

Perl

sub upload_offline_conversions {
  my $client                        = shift;
  my $conversion_name               = shift;
  my $gclid                         = shift;
  my $conversion_time               = shift;
  my $conversion_value              = shift;
  my @offline_conversion_operations = ();

  # Associate offline conversions with the existing named conversion tracker. If
  # this tracker was newly created, it may be a few hours before it can accept
  # conversions.
  my $feed = Google::Ads::AdWords::v201809::OfflineCallConversionFeed->new({
      conversionName  => $conversion_name,
      conversionTime  => $conversion_time,
      conversionValue => $conversion_value,
      googleClickId   => $gclid
  });

  my $offline_conversion_operation =
    Google::Ads::AdWords::v201809::OfflineCallConversionFeedOperation->new({
      operator => "ADD",
      operand  => $feed
    });

  push @offline_conversion_operations, $offline_conversion_operation;

  # Add the upload conversion.
  my $feed_result =
    $client->OfflineCallConversionFeedService()
    ->mutate({operations => @offline_conversion_operations});

  # Display results.
  if ($feed_result->get_value()) {
    foreach my $oc_feed (@{$feed_result->get_value()}) {
      printf "Uploaded offline conversion value of "%s" for Google Click " .
        "ID "%s" was created.n",
        $oc_feed->get_conversionName(),
        $oc_feed->get_googleClickId();
    }
  } else {
    print "No offline conversion were added.n";
    return;
  }

  return 1;
}

C#

public void Run(AdWordsUser user, string conversionName, string gClid,
    string conversionTime, double conversionValue)
{
    using (OfflineConversionFeedService offlineConversionFeedService =
        (OfflineConversionFeedService) user.GetService(AdWordsService.v201809
            .OfflineConversionFeedService))
    {
        try
        {
            // Associate offline conversions with the existing named conversion tracker. If
            // this tracker was newly created, it may be a few hours before it can accept
            // conversions.
            OfflineConversionFeed feed = new OfflineConversionFeed
            {
                conversionName = conversionName,
                conversionTime = conversionTime,
                conversionValue = conversionValue,
                googleClickId = gClid
            };

            // Optional: To upload fractional conversion credits, set the external
            // attribution model and credit. To use this feature, your conversion tracker
            // should be marked as externally attributed. See
            // https://developers.google.com/adwords/api/docs/guides/conversion-tracking#importing_externally_attributed_conversions
            // to learn more about importing externally attributed conversions.

            // feed.externalAttributionModel = "Linear";
            // feed.externalAttributionCredit = 0.3;

            OfflineConversionFeedOperation offlineConversionOperation =
                new OfflineConversionFeedOperation
                {
                    @operator = Operator.ADD,
                    operand = feed
                };

            OfflineConversionFeedReturnValue offlineConversionRetval =
                offlineConversionFeedService.mutate(new OfflineConversionFeedOperation[]
                {
                    offlineConversionOperation
                });

            OfflineConversionFeed newFeed = offlineConversionRetval.value[0];

            Console.WriteLine(
                "Uploaded offline conversion value of {0} for Google Click ID = " +
                "'{1}' to '{2}'.", newFeed.conversionValue, newFeed.googleClickId,
                newFeed.conversionName);
        }
        catch (Exception e)
        {
            throw new System.ApplicationException("Failed upload offline conversions.", e);
        }
    }
}

VB

''' 
''' Runs the code example.
''' 
''' The AdWords user.
''' The name of the upload conversion to be
''' created.
''' The Google Click ID of the click for which offline
''' conversions are uploaded.
''' The conversion value to be uploaded.
''' 
''' The conversion time, in yyyymmdd hhmmss
''' format.
Public Sub Run(ByVal user As AdWordsUser, ByVal conversionName As String,
               ByVal gClid As String, ByVal conversionTime As String,
               ByVal conversionValue As Double)
    Using _
        offlineConversionFeedService As OfflineConversionFeedService =
            CType(
                user.GetService(
                    AdWordsService.v201809.OfflineConversionFeedService),
                OfflineConversionFeedService)

        Try
            ' Associate offline conversions with the existing named conversion tracker. If
            ' this tracker was newly created, it may be a few hours before it can accept
            ' conversions.
            Dim feed As New OfflineConversionFeed()
            feed.conversionName = conversionName
            feed.conversionTime = conversionTime
            feed.conversionValue = conversionValue
            feed.googleClickId = gClid

            ' Optional: To upload fractional conversion credits, set the external
            ' attribution model and credit. To use this feature, your conversion tracker
            ' should be marked as externally attributed. See
            ' https://developers.google.com/adwords/api/docs/guides/conversion-tracking#importing_externally_attributed_conversions
            ' to learn more about importing externally attributed conversions.

            ' feed.externalAttributionModel = "Linear"
            ' feed.externalAttributionCredit = 0.3

            Dim offlineConversionOperation As New OfflineConversionFeedOperation()
            offlineConversionOperation.operator = [Operator].ADD
            offlineConversionOperation.operand = feed

            Dim offlineConversionRetval As OfflineConversionFeedReturnValue =
                    offlineConversionFeedService.mutate(
                        New OfflineConversionFeedOperation() {offlineConversionOperation})

            Dim newFeed As OfflineConversionFeed = offlineConversionRetval.value(0)

            Console.WriteLine(
                "Uploaded offline conversion value of {0} for Google Click ID = " &
                "'{1}' to '{2}'.", newFeed.conversionValue, newFeed.googleClickId,
                newFeed.conversionName)
        Catch e As Exception
            Throw _
                New System.ApplicationException("Failed to upload offline conversions.", e)
        End Try
    End Using
End Sub

Importing externally attributed conversions

If you use third-party tools or homegrown solutions to track conversions, then
you may want to give Google Ads only part of the credit for the conversion.
Sometimes, you may also want to distribute a conversion’s credit across
multiple clicks. Externally attributed conversion
imports
allows you to upload
conversions with fractional credit assigned to each gclid.

To upload fractional credits, you need to follow the instructions for uploading
offline conversions
, and perform these
additional steps:

  1. When creating your
    UploadConversion
    object, mark it as externally attributed by setting the
    isExternallyAttributed
    property to true.

  2. Specify the
    externalAttributionModel
    and
    externalAttributionCredit
    properties for your
    OfflineConversionFeed
    object when uploading conversions.

Validation rules

There are several requirements that must be met when uploading an
OfflineConversionFeed.

To avoid an OfflineConversionError.INVALID_CONVERSION_TYPE error, the
conversionName must refer to an UploadConversion where:

  • The UploadConversion had a
    status
    of ENABLED at the time of the click.

  • The UploadConversion existed in the effective conversion account of the
    click’s Google Ads account at the time of the click. If the account was not
    using cross-account conversion
    tracking
    at the time of the
    click, Google Ads will look for the UploadConversion in the account used to
    upload conversions. You can find your account’s effective conversion tracking
    account under Tools > Conversions in the Google Ads UI, but keep
    in mind that this will show you the current effective conversion tracking
    account, which may differ from the effective conversion tracking account in
    place at the time of the click.

In addition, the following conditions must be met:

  • The conversionTime must be after the click happened,
    to avoid an OfflineConversionError.CONVERSION_PRECEDES_CLICK
    error.

  • The conversionTime must be before the click-through conversion lookback
    window

    you specified for the UploadConversion object, to avoid an
    OfflineConversionError.EXPIRED_CLICK error.

  • The conversionValue must be greater than or equal to zero.

  • The conversionTime must have a timezone
    ID
    . The timezone ID can be for any
    valid timezone: It does not have to match the account’s timezone.

Tips

A few things to keep in mind when creating an OfflineConversionFeed:

  • Upload operations are atomic; if a conversion has a bad
    GCLID or is too old, none of the accompanying conversions will be uploaded.
    Use partial failures to avoid
    this situation.

  • Although duplicate uploads of a conversion (same GCLID, name, and time)
    are permitted, only the first instance is recorded.

  • Uploaded conversions will be reflected in reports for the
    impression date of the original click,
    not the date of the upload request or the date of the conversionTime of the
    OfflineConversionFeeds.

  • We recommend you wait 6 hours after creating the UploadConversion before
    uploading.

  • It takes up to 3 hours for imported conversion statistics to appear in your
    Google Ads account for last-click
    attribution
    . For other search
    attribution models, it can take longer than 3 hours.

  • When uploading click conversions for multiple accounts, you can specify the
    clientCustomerId of a common manager account and include operations with
    GCLIDs from across multiple accounts. A conversion is attributed to the proper
    account based on the origin of its GCLID.

  • When uploading click conversions with cross-account conversion tracking
    enabled, the conversion type must be in the manager account, rather than in the
    account associated with the GCLID.

Code examples

The Remarketing folder of each client
library
contains a code example for
uploading offline conversions:

Importing call conversions

You can use the AdWords API to upload
offline call conversions into
Google Ads, giving you more flexibility in associating calls
with conversions.

This section describes how to use the AdWords API to construct a feed for
importing your offline call conversions.

Setup

The first step is to create a conversion tracker for offline call conversions.
You can create one using the Google Ads
UI
or through code.
Through code you would create an
UploadCallConversion.
The process is similar to the example found in Setup for importing click
conversions
. In the example, use
UploadCallConversion
instead of
UploadConversion.

Uploading offline call conversions

Once you’ve created the
UploadCallConversion
object, you need to associate your offline call conversions with it by passing
the caller ID, conversion time (with timezone
ID
), conversion name, and optionally the
conversion value and conversion currency to
OfflineCallConversionFeedService:

Java

/**
 * Runs the example.
 *
 * @param adWordsServices the services factory.
 * @param session the session.
 * @param callerId the caller ID of the call.
 * @param callStartTime the call start time of the call.
 * @param conversionName the name of the conversion tracker.
 * @param conversionTime the date and time of the conversion.
 * @param conversionValue the value of the conversion.
 * @throws ApiException if the API request failed with one or more service errors.
 * @throws RemoteException if the API request failed due to other errors.
 */
public static void runExample(
    AdWordsServicesInterface adWordsServices,
    AdWordsSession session,
    String callerId,
    String callStartTime,
    String conversionName,
    String conversionTime,
    double conversionValue)
    throws RemoteException {

  // Get the OfflineCallConversionFeedService.
  OfflineCallConversionFeedServiceInterface offlineCallConversionFeedService =
      adWordsServices.get(session, OfflineCallConversionFeedServiceInterface.class);

  // Associate offline call conversions with the existing named conversion tracker. If this
  // tracker was newly created, it may be a few hours before it can accept conversions.
  OfflineCallConversionFeed feed = new OfflineCallConversionFeed();
  feed.setCallerId(callerId);
  feed.setCallStartTime(callStartTime);
  feed.setConversionName(conversionName);
  feed.setConversionTime(conversionTime);
  feed.setConversionValue(conversionValue);

  OfflineCallConversionFeedOperation offlineCallConversionOperation =
      new OfflineCallConversionFeedOperation();
  offlineCallConversionOperation.setOperator(Operator.ADD);
  offlineCallConversionOperation.setOperand(feed);

  // This example uploads only one call conversion, but you can upload multiple call conversions
  // by passing additional operations.
  OfflineCallConversionFeedReturnValue offlineCallConversionReturnValue =
      offlineCallConversionFeedService.mutate(
          new OfflineCallConversionFeedOperation[] {offlineCallConversionOperation});

  // Display results.
  for (OfflineCallConversionFeed feedResult : offlineCallConversionReturnValue.getValue()) {
    System.out.printf(
        "Uploaded offline conversion value of %.4f for caller ID '%s'.%n",
        feedResult.getConversionValue(), feedResult.getCallerId());
  }
}

PHP

public static function runExample(
    AdWordsServices $adWordsServices,
    AdWordsSession $session,
    $callerId,
    $callStartTime,
    $conversionName,
    $conversionTime,
    $conversionValue
) {
    $offlineCallConversionService = $adWordsServices->get(
        $session,
        OfflineCallConversionFeedService::class
    );

    // Associate offline call conversions with the existing named conversion
    // tracker. If this tracker was newly created, it may be a few hours before
    // it can accept conversions.
    $feed = new OfflineCallConversionFeed();
    $feed->setCallerId($callerId);
    $feed->setCallStartTime($callStartTime);
    $feed->setConversionName($conversionName);
    $feed->setConversionTime($conversionTime);
    $feed->setConversionValue($conversionValue);

    $offlineCallConversionOperations = [];
    $offlineCallConversionOperation = new OfflineCallConversionFeedOperation();
    $offlineCallConversionOperation->setOperator(Operator::ADD);
    $offlineCallConversionOperation->setOperand($feed);
    $offlineCallConversionOperations[] = $offlineCallConversionOperation;

    // This example uploads only one call conversion, but you can upload
    // multiple call conversions by passing additional operations.
    $result = $offlineCallConversionService->mutate($offlineCallConversionOperations);

    $feed = $result->getValue()[0];
    printf(
        "Uploaded offline call conversion value of '%s' for caller ID '%s'.n",
        $feed->getConversionValue(),
        $feed->getCallerId()
    );
}

Python

def main(client, caller_id, call_start_time, conversion_name, conversion_time,
         conversion_value):
  # Initialize appropriate services.
  occ_feed_service = client.GetService(
      'OfflineCallConversionFeedService', version='v201809')

  # Associate offline call conversions with the existing named conversion
  # tracker. If this tracker was newly created, it may be a few hours before it
  # can accept conversions.
  feed = {
      'callerId': caller_id,
      'callStartTime': call_start_time,
      'conversionName': conversion_name,
      'conversionTime': conversion_time,
      'conversionValue': conversion_value,
  }

  occ_operations = [{'operator': 'ADD', 'operand': feed}]

  occ_response = occ_feed_service.mutate(occ_operations)
  values = occ_response['value']

  if values:
    for occ_feed in values:
      print('Uploaded offline call conversion value of "%s" for caller ID '
            '"%s".n' % (occ_feed['conversionName'], occ_feed['callerId']))
  else:
    print('No offline call conversions were added.')

Ruby

occ_feed_srv =
    adwords.service(:OfflineCallConversionFeedService, API_VERSION)

# Associate offline conversions with the existing named conversion tracker. If
# this tracker was newly created, it may be a few hours before it can accept
# conversions.
feed = {
  :caller_id => caller_id,
  :call_start_time => call_start_time,
  :conversion_name => conversion_name,
  :conversion_time => conversion_time,
  :conversion_value => conversion_value
}

occ_operations = [{
  :operator => 'ADD',
  :operand => feed
}]

occ_response = occ_feed_srv.mutate(occ_operations)

if occ_response[:value]
  occ_response[:value].each do |occ_feed|
    puts 'Uploaded offline call conversion value "%s" for caller ID "%s"' %
        [occ_feed[:conversion_name], occ_feed[:caller_id]]
  end
end

Perl

sub upload_offline_call_conversions {
  my $client                             = shift;
  my $caller_id                          = shift;
  my $call_start_time                    = shift;
  my $conversion_name                    = shift;
  my $conversion_time                    = shift;
  my $conversion_value                   = shift;
  my @offline_call_conversion_operations = ();

  # Associate offline call conversions with the existing named
  # conversion tracker. If this tracker was newly created, it may be a
  # few hours before it can accept conversions.
  my $feed = Google::Ads::AdWords::v201809::OfflineCallConversionFeed->new({
    callerId        => $caller_id,
    callStartTime   => $call_start_time,
    conversionName  => $conversion_name,
    conversionTime  => $conversion_time,
    conversionValue => $conversion_value
  });

  my $offline_call_conversion_operation =
    Google::Ads::AdWords::v201809::OfflineCallConversionFeedOperation->new({
      operator => "ADD",
      operand  => $feed
    });

  push @offline_call_conversion_operations, $offline_call_conversion_operation;

  # This example uploads only one call conversion, but you can upload multiple
  # call conversions by passing additional operations.
  my $result =
    $client->OfflineCallConversionFeedService()
    ->mutate({operations => @offline_call_conversion_operations});

  # Display results.
  if ($result->get_value()) {
    foreach my $feed_result (@{$result->get_value()}) {
      printf "Uploaded offline call conversion value of "%s" for caller ID " .
        ""%s".n",
        $feed_result->get_conversionValue(),
        $feed_result->get_callerId();
    }
  } else {
    print "No offline call conversions were added.n";
    return;
  }

  return 1;
}

C#

public void Run(AdWordsUser user, string conversionName, string callStartTime,
    string callerId, string conversionTime, double conversionValue)
{
    using (OfflineCallConversionFeedService offlineCallConversionFeedService =
        (OfflineCallConversionFeedService) user.GetService(AdWordsService.v201809
            .OfflineCallConversionFeedService))
    {
        // Associate offline call conversions with the existing named conversion tracker.
        // If this tracker was newly created, it may be a few hours before it can accept
        // conversions.
        OfflineCallConversionFeed feed = new OfflineCallConversionFeed
        {
            callerId = callerId,
            callStartTime = callStartTime,
            conversionName = conversionName,
            conversionTime = conversionTime,
            conversionValue = conversionValue
        };

        OfflineCallConversionFeedOperation offlineCallConversionOperation =
            new OfflineCallConversionFeedOperation
            {
                @operator = Operator.ADD,
                operand = feed
            };

        try
        {
            // This example uploads only one call conversion, but you can upload
            // multiple call conversions by passing additional operations.
            OfflineCallConversionFeedReturnValue offlineCallConversionReturnValue =
                offlineCallConversionFeedService.mutate(
                    new OfflineCallConversionFeedOperation[]
                    {
                        offlineCallConversionOperation
                    });

            // Display results.
            foreach (OfflineCallConversionFeed feedResult in
                offlineCallConversionReturnValue.value)
            {
                Console.WriteLine(
                    "Uploaded offline call conversion value of {0} for caller ID '{1}'.",
                    feedResult.conversionValue, feedResult.callerId);
            }
        }
        catch (Exception e)
        {
            throw new System.ApplicationException(
                "Failed to upload offline call conversions.", e);
        }
    }
}

VB

Using offlineCallConversionFeedService As OfflineCallConversionFeedService =
    CType(user.GetService(AdWordsService.v201809.OfflineCallConversionFeedService),
          OfflineCallConversionFeedService)

    ' Associate offline call conversions with the existing named conversion tracker. If
    ' this tracker was newly created, it may be a few hours before it can accept
    ' conversions.
    Dim feed As New OfflineCallConversionFeed()
    feed.callerId = callerId
    feed.callStartTime = callStartTime
    feed.conversionName = conversionName
    feed.conversionTime = conversionTime
    feed.conversionValue = conversionValue

    Dim feedOperation As New OfflineCallConversionFeedOperation()
    feedOperation.operator = [Operator].ADD
    feedOperation.operand = feed

    Try
        ' This example uploads only one call conversion, but you can upload
        ' multiple call conversions by passing additional operations.
        Dim offlineCallConversionReturnValue As OfflineCallConversionFeedReturnValue =
                offlineCallConversionFeedService.mutate(
                    New OfflineCallConversionFeedOperation() _
                                                           {feedOperation})

        ' Display results.
        For Each feedResult As OfflineCallConversionFeed In _
            offlineCallConversionReturnValue.value
            Console.WriteLine(
                "Uploaded offline call conversion value of {0} for caller ID '{1}'.",
                feedResult.conversionValue, feedResult.callerId)
        Next
    Catch e As Exception
        Throw _
            New System.ApplicationException("Failed to upload offline call conversions.",
                                            e)
    End Try
End Using

Validation rules

There are several requirements that must be met when uploading an
OfflineCallConversionFeed.

To avoid an OfflineCallConversionError.INVALID_CONVERSION_TYPE error, the
conversionName must refer to an UploadCallConversion where:

  • The UploadCallConversion had a
    status
    of ENABLED at the time of the call.

  • The UploadCallConversion existed in the effective conversion account of the
    call’s Google Ads account at the time of the call. If the account was not
    using cross-account conversion
    tracking
    at the time of the call,
    Google Ads will look for the UploadCallConversion in the account used to upload
    conversions. You can find your account’s effective conversion tracking account
    under Tools > Conversions in the Google Ads UI, but keep in mind
    that this will show you the current effective conversion tracking account,
    which may differ from the effective conversion tracking account in place at the
    time of the call.

In addition, the following conditions must be met:

  • The conversionValue must be greater than or equal to zero.

  • The conversionTime must have a timezone
    ID
    . The timezone ID can be for any
    valid timezone: It does not have to match the account’s timezone.

Tips

A few things to keep in mind when creating an OfflineCallConversionFeed:

  • We recommend you wait 6 hours after creating the UploadCallConversion
    before uploading.

  • It takes up to 3 hours for imported conversion statistics to appear in your
    Google Ads account.

  • Although duplicate uploads of a conversion (same caller ID, name, and time)
    are permitted, only the first instance is recorded.

Code examples

The Remarketing folder of each client
library
contains a code example for
uploading offline call conversions:

Adjusting conversions

Once a conversion has already been reported to Google Ads, you can adjust the
conversion
at a later point in
time in the API.

Setup

In order to adjust a conversion, you must first have conversion tracking set
up
, and you must also have
reported on the conversions that you are about to adjust.

Uploading conversion adjustments

There are two types of adjustments that can be made. When you have a Google
click ID (GCLID) and conversion time available, you can adjust a conversion by
uploading a
GclidOfflineConversionAdjustmentFeed object.
You can also adjust a conversion by uploading an OrderIdOfflineConversionAdjustmentFeed object
when you have an order ID available instead of a click ID and conversion time.
Both these adjustment types would be uploaded through the OfflineConversionAdjustmentFeedService.

Validation rules

Here are some things to keep in mind while adjusting conversions in the API:

  • You can upload to other conversion types that are not traditionally supported
    by the API as long as you have the conversion tracker name.
  • Only the account that manages conversion types for accounts under it will be
    able to upload adjustments.
  • The fields specifying time require a time zone ID
    which does not need to be that of the account.
  • The conversion has to already be reported in order to adjust it.

Code examples

The Remarketing folder of each client
library
contains a code example for
adjusting conversions:

Importing Store Sales Direct conversions

You can use the AdWords API to upload
Store Sales Direct Upload conversions
into Google Ads.

Setup

The first step is to create import conversion types. This must be done for each
unique conversion “classification”. You can create them only
using the Google Ads UI.
The given conversionName is a unique identifier for this conversion event.
After creating your import conversion types, you are ready to start uploading
Store Sales Direct conversions using either the UI or the AdWords API.

Uploading Store Sales Direct conversions

Once you’ve created the conversion tracker, you need to associate Store Sales
Direct conversions with it by passing the conversion name and store
transactions in the
OfflineDataUpload object
through the OfflineDataUploadService.

Validation rules

There are several requirements that must be met when uploading an
OfflineDataUpload object.

To avoid an OfflineDataUploadError.INVALID_CONVERSION_TYPE error, the
conversionName must refer to a conversion tracker where:

  • The conversion tracker was enabled at the time of the click.

  • The conversion tracker existed in the effective conversion account of the
    click’s Google Ads account at the time of the click. If the account was not
    using cross-account conversion
    tracking
    at the time of the click,
    Google Ads will look for the conversion tracker in the account used to upload
    conversions. You can find your account’s effective conversion tracking account
    under Tools > Conversions in the Google Ads UI, but keep in mind
    that this will show you the current effective conversion tracking account,
    which may differ from the effective conversion tracking account in place at the
    time of the click.

In addition, the following conditions must be met:

  • The transactionAmount must be greater than zero.

  • The transactionTime must have a timezone
    ID
    . The timezone ID can be for any
    valid timezone: It does not have to match the account’s timezone.

Code examples

The Remarketing folder of each client
library
contains a code example for
uploading offline data:

Leave a Reply

Your email address will not be published. Required fields are marked *

Back to top button
Close