The AdWords API will sunset on April 27, 2022. Migrate to the Google Ads API to take advantage of the latest Google Ads features.

Tracking and Importing Conversions

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).

Mapping of UI conversion categories

On September 2020, conversion categories were expanded to allow finer grained categorization of conversions. Not all of the new conversion action categories are available in this API. The following table summarizes the mapping of categories that appear in the UI to the equivalent mapped result in the API:

New Conversion Category Mapping to ConversionTracker.Category
Add to cart LEAD
Begin checkout LEAD
Purchase PURCHASE
Subscribe PURCHASE
Sign-up SIGNUP
Phone call lead LEAD
Imported lead LEAD
Submit lead form LEAD
Book appointment LEAD
Request quote LEAD
Get directions LEAD
Outbound click LEAD
Contact LEAD
Download DOWNLOAD
Page view PAGE_VIEW
Engagement DEFAULT
Store visit DEFAULT
Store sale PURCHASE
Other DEFAULT

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

Field Name Description
Conversions Main field for conversions reporting that reflects conversion actions you want to bid on. Only conversions from conversion actions (ConversionTracker) that have the excludeFromBidding field set to false are included.
ConversionRate Conversions divided by total clicks that can be conversion-tracked. This is how often, on average, an ad interaction leads to a conversion that has the excludeFromBidding field set to false.
ConversionValue The total value of all conversion actions (ConversionTracker) that have the excludeFromBidding field set to false.
CostPerConversion Total cost divided by Conversions.
ValuePerConversion ConversionValue divided by Conversions.

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.

Field Name Description
CostPerCurrentModelAttributedConversion Historical CostPerConversion data based on the current attribution model.
CurrentModelAttributedConversionValue Historical ConversionValue data based on the current attribution model.
CurrentModelAttributedConversions Historical Conversions data based on the current attribution model.
ValuePerCurrentModelAttributedConversion Historical ValuePerConversion data based on 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

''' <summary>
''' Runs the code example.
''' </summary>
''' <param name="user">The AdWords user.</param>
''' <param name="conversionName">The name of the upload conversion to be
''' created.</param>
''' <param name="gClid">The Google Click ID of the click for which offline
''' conversions are uploaded.</param>
''' <param name="conversionValue">The conversion value to be uploaded.
''' </param>
''' <param name="conversionTime">The conversion time, in yyyymmdd hhmmss
''' format.</param>
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 status of the UploadConversion is ENABLED.
  • The UploadConversion exists in the effective conversion account of the click's Google Ads account.
  • At the time of the click, conversion tracking was enabled in the effective conversion account of the click's Google Ads account.

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 status of the UploadCallConversion is ENABLED.
  • The UploadCallConversion exists in the effective conversion account of the click's Google Ads account.
  • At the time of the call, conversion tracking was enabled in the effective conversion account of the click's Google Ads account.

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 status of the conversion tracker is ENABLED.
  • The conversion tracker exists in the effective conversion account of the click's Google Ads account.

In addition, the following conditions must be met:

  • At the time of the click, conversion tracking was enabled in the effective conversion account of the click's Google Ads account.

  • 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: