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:
- Phone number clicks corresponds to
AdWordsConversionTracker
(withtrackingCodeType
asCLICK_TO_CALL
). - Calls from ads corresponds to
AdCallMetricsConversion
. - Calls from websites corresponds to
WebsiteCallMetricsConversion
.
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:
- All conversion types defined by the manager account used by the account for cross-account conversion tracking.
- 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.
- 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:
When creating your
UploadConversion
object, mark it as externally attributed by setting theisExternallyAttributed
property totrue
.Specify the
externalAttributionModel
andexternalAttributionCredit
properties for yourOfflineConversionFeed
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 theUploadConversion
isENABLED
. - 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 anOfflineConversionError.CONVERSION_PRECEDES_CLICK
error.The
conversionTime
must be before the click-through conversion lookback window you specified for theUploadConversion
object, to avoid anOfflineConversionError.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 theOfflineConversionFeeds
.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:
Java
Upload offline conversionsPHP
Upload offline conversionsPython
Upload offline conversionsRuby
Upload offline conversionsPerl
Upload offline conversionsC#
Upload offline conversionsVB
Upload offline conversionsImporting 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 theUploadCallConversion
isENABLED
. - 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:
Java
Upload offline call conversionsPHP
Upload offline call conversionsPython
Upload offline call conversionsRuby
Upload offline call conversionsPerl
Upload offline call conversionsC#
Upload offline call conversionsVB
Upload offline call conversionsAdjusting 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:
Java
Upload conversion adjustmentsPHP
Upload conversion adjustmentsPython
Upload conversion adjustmentsRuby
Upload conversion adjustmentsPerl
Upload conversion adjustmentsC#
Upload conversion adjustmentsVB
Upload conversion adjustmentsImporting 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 isENABLED
. - 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: