Stay organized with collectionsSave and categorize content based on your preferences.
You must enable conversion tracking in your Google Ads conversion account in
order to record conversions. This guide provides details on how to confirm
whether conversion tracking is enabled, enable it if it isn't enabled already,
and retrieve information about existing conversion actions.
Most conversion actions also require additional steps on your part to track
them. For more information on the various conversion action types and their
requirements, see theCreate conversion actions guide.
Thegoogle_ads_conversion_customerfield indicates the Google Ads account that
creates and manages conversions for this customer. For customers usingcross-account conversion tracking,
this is the ID of a manager account. The Google Ads conversion customer ID should be
given as thecustomer_idin Google Ads API requests to create and manage conversions.
Note that this field is populated even if conversion tracking is not enabled.
Theconversion_tracking_statusfield indicates whether conversion tracking is enabled and whether the account
is using cross-account conversion tracking.
Create a conversion action under the Google Ads conversion customer
If theconversion_tracking_statusvalue isNOT_CONVERSION_TRACKED,
conversion tracking is not enabled for the account. Enable conversion tracking
by creating at least oneConversionActionin
the Google Ads conversion account, like in the following example. Alternatively, you
can create a conversion action in the UI by following the instructions in theHelp Centerfor the
conversion type you want to enable.
Note that enhanced conversions are enabled automatically when sent through the
Google Ads API, but they can be disabled through the Google Ads UI.
defmain(client:GoogleAdsClient,customer_id:str)->None:conversion_action_service:ConversionActionServiceClient=(client.get_service("ConversionActionService"))# Create the operation.conversion_action_operation:ConversionActionOperation=client.get_type("ConversionActionOperation")# Create conversion action.conversion_action:ConversionAction=conversion_action_operation.create# Note that conversion action names must be unique. If a conversion action# already exists with the specified conversion_action_name, the create# operation will fail with a ConversionActionError.DUPLICATE_NAME error.conversion_action.name=f"Earth to Mars Cruises Conversion{uuid.uuid4()}"conversion_action.type_=(client.enums.ConversionActionTypeEnum.UPLOAD_CLICKS)conversion_action.category=(client.enums.ConversionActionCategoryEnum.DEFAULT)conversion_action.status=client.enums.ConversionActionStatusEnum.ENABLEDconversion_action.view_through_lookback_window_days=15# Create a value settings object.value_settings:ConversionAction.ValueSettings=(conversion_action.value_settings)value_settings.default_value=15.0value_settings.always_use_default_value=True# Add the conversion action.conversion_action_response:MutateConversionActionsResponse=(conversion_action_service.mutate_conversion_actions(customer_id=customer_id,operations=[conversion_action_operation],))print("Created conversion action "f'"{conversion_action_response.results[0].resource_name}".')
defadd_conversion_action(customer_id)# GoogleAdsClient will read a config file from# ENV['HOME']/google_ads_config.rb when called without parametersclient=Google::Ads::GoogleAds::GoogleAdsClient.new# Add a conversion action.conversion_action=client.resource.conversion_actiondo|ca|ca.name="Earth to Mars Cruises Conversion#{(Time.new.to_f*100).to_i}"ca.type=:UPLOAD_CLICKSca.category=:DEFAULTca.status=:ENABLEDca.view_through_lookback_window_days=15# Create a value settings object.ca.value_settings=client.resource.value_settingsdo|vs|vs.default_value=15vs.always_use_default_value=trueendend# Create the operation.conversion_action_operation=client.operation.create_resource.conversion_action(conversion_action)# Add the ad group ad.response=client.service.conversion_action.mutate_conversion_actions(customer_id:customer_id,operations:[conversion_action_operation],)puts"New conversion action with resource name =#{response.results.first.resource_name}."end
subadd_conversion_action{my($api_client,$customer_id)=@_;# Note that conversion action names must be unique.# If a conversion action already exists with the specified conversion_action_name,# the create operation fails with error ConversionActionError.DUPLICATE_NAME.my$conversion_action_name="Earth to Mars Cruises Conversion #".uniqid();# Create a conversion action.my$conversion_action=Google::Ads::GoogleAds::V21::Resources::ConversionAction->new({name=>$conversion_action_name,category=>DEFAULT,type=>WEBPAGE,status=>ENABLED,viewThroughLookbackWindowDays=>15,valueSettings=>Google::Ads::GoogleAds::V21::Resources::ValueSettings->new({defaultValue=>23.41,alwaysUseDefaultValue=>"true"})});# Create a conversion action operation.my$conversion_action_operation=Google::Ads::GoogleAds::V21::Services::ConversionActionService::ConversionActionOperation->new({create=>$conversion_action});# Add the conversion action.my$conversion_actions_response=$api_client->ConversionActionService()->mutate({customerId=>$customer_id,operations=>[$conversion_action_operation]});printf"New conversion action added with resource name: '%s'.\n",$conversion_actions_response->{results}[0]{resourceName};return1;}
Make sure theconversion_action_typeis set to the correctConversionActionTypevalue.
For more guidance on creating conversion actions in the Google Ads API, seeCreate Conversion Actions.
Retrieve an existing conversion action
You can retrieve details for an existing conversion action by issuing the
following query. Make sure the customer ID in the request is set to the Google Ads
conversion customer you identified above, and the conversion action type is set
to the correctConversionActionTypevalue.
All conversion actions defined by the manager account used by the account for
cross-account conversion tracking
All conversion actions on which the customer has accrued stats, including
system-defined actions, and actions owned by the manager even if that manager
unlinks subsequently
All actions the customer has defined in their own account
Analytics conversions created in linked Google Analytics properties.
This includes actions for Analytics conversions not imported into Google Ads,
which have a status ofHIDDEN.
Starting inv19.1, you can use the
Google Ads API to opt into cross-conversion tracking whencreatingclient accounts.
Starting inv20, you can use the
Google Ads API to opt into cross-conversion tracking both when creatingandupdating
client accounts.
When updating an existing client account, you can opt into cross-account
conversion tracking by setting theconversion_tracking_setting.google_ads_conversion_customerfield. This field should be set to theresource nameof the manager
account that should manage conversion actions on behalf of the client account.
This manager account must also be the account that issues theupdaterequest
for the client account.
NOTE: using the Google Ads API to modify the cross-account conversion tracking
settings of a client account is an allow-list only feature. To use it, contact
your account manager.
When you opt into cross-account conversion tracking, or switch the conversion
tracking manager for an existing client account, the same caveats apply as if
you were tomake this change in the UI.
Specifically:
The client account will adopt the default conversion value rules, and the
default customer lifecycle goals of its new conversion tracking manager.
Campaigns that target a specific conversion action will switch to using the
conversion manager account's default conversion goals. If you continue to
target a specific conversion action, that can produce inconsistent behavior,
as the manager account may not have the same goals as the client account. Make
sure that your campaigns are optimized to the right goals.
If an account belongs to more than one manager account, it can only use
conversion actions from one manager. If no conversion tracking account is
specified, the account will use itself as the conversion tracking account by
default.
Create conversion actions
To measure conversions, set up aConversionActionfor thetypeof
conversion action you want to track. For example, an online purchase and a phone
call require different conversion actions.
The best way to set up new conversion actions in the API is to use theAdd Conversion Action code example below. The sample handles
all the background authentication tasks for you, and walks you through creating
aConversionAction.
Most conversion actions also require additional steps on your part to track
them. For example, to track conversions on your website, you must add a code
snippet called atagto the conversion page on your website. For detailed requirements of other
conversion action types, see ourHelp Center article.
Code example
The following code example walks you through the process of creating a new
conversion action. Specifically, it creates a conversion action with thetypeset toUPLOAD_CLICKS.
It also sets thecategorytoDEFAULT.
The following default settings apply:
The Google Ads API sets theprimary_for_goalfield
automatically, but you can set this field explicitly to control how a
conversion action impacts reporting and bidding in your account whencombined
with your conversion goals.
defmain(client:GoogleAdsClient,customer_id:str)->None:conversion_action_service:ConversionActionServiceClient=(client.get_service("ConversionActionService"))# Create the operation.conversion_action_operation:ConversionActionOperation=client.get_type("ConversionActionOperation")# Create conversion action.conversion_action:ConversionAction=conversion_action_operation.create# Note that conversion action names must be unique. If a conversion action# already exists with the specified conversion_action_name, the create# operation will fail with a ConversionActionError.DUPLICATE_NAME error.conversion_action.name=f"Earth to Mars Cruises Conversion{uuid.uuid4()}"conversion_action.type_=(client.enums.ConversionActionTypeEnum.UPLOAD_CLICKS)conversion_action.category=(client.enums.ConversionActionCategoryEnum.DEFAULT)conversion_action.status=client.enums.ConversionActionStatusEnum.ENABLEDconversion_action.view_through_lookback_window_days=15# Create a value settings object.value_settings:ConversionAction.ValueSettings=(conversion_action.value_settings)value_settings.default_value=15.0value_settings.always_use_default_value=True# Add the conversion action.conversion_action_response:MutateConversionActionsResponse=(conversion_action_service.mutate_conversion_actions(customer_id=customer_id,operations=[conversion_action_operation],))print("Created conversion action "f'"{conversion_action_response.results[0].resource_name}".')
defadd_conversion_action(customer_id)# GoogleAdsClient will read a config file from# ENV['HOME']/google_ads_config.rb when called without parametersclient=Google::Ads::GoogleAds::GoogleAdsClient.new# Add a conversion action.conversion_action=client.resource.conversion_actiondo|ca|ca.name="Earth to Mars Cruises Conversion#{(Time.new.to_f*100).to_i}"ca.type=:UPLOAD_CLICKSca.category=:DEFAULTca.status=:ENABLEDca.view_through_lookback_window_days=15# Create a value settings object.ca.value_settings=client.resource.value_settingsdo|vs|vs.default_value=15vs.always_use_default_value=trueendend# Create the operation.conversion_action_operation=client.operation.create_resource.conversion_action(conversion_action)# Add the ad group ad.response=client.service.conversion_action.mutate_conversion_actions(customer_id:customer_id,operations:[conversion_action_operation],)puts"New conversion action with resource name =#{response.results.first.resource_name}."end
subadd_conversion_action{my($api_client,$customer_id)=@_;# Note that conversion action names must be unique.# If a conversion action already exists with the specified conversion_action_name,# the create operation fails with error ConversionActionError.DUPLICATE_NAME.my$conversion_action_name="Earth to Mars Cruises Conversion #".uniqid();# Create a conversion action.my$conversion_action=Google::Ads::GoogleAds::V21::Resources::ConversionAction->new({name=>$conversion_action_name,category=>DEFAULT,type=>WEBPAGE,status=>ENABLED,viewThroughLookbackWindowDays=>15,valueSettings=>Google::Ads::GoogleAds::V21::Resources::ValueSettings->new({defaultValue=>23.41,alwaysUseDefaultValue=>"true"})});# Create a conversion action operation.my$conversion_action_operation=Google::Ads::GoogleAds::V21::Services::ConversionActionService::ConversionActionOperation->new({create=>$conversion_action});# Add the conversion action.my$conversion_actions_response=$api_client->ConversionActionService()->mutate({customerId=>$customer_id,operations=>[$conversion_action_operation]});printf"New conversion action added with resource name: '%s'.\n",$conversion_actions_response->{results}[0]{resourceName};return1;}
Setting this attribute to a value outside of the allowed range results in aRangeError.TOO_LOWorRangeError.TOO_HIGHerror.
This attribute must be in the range[1,60]for anAD_CALLorWEBSITE_CALLconversion action. For most other conversion actions, the
allowed range is[1,30].
include_in_conversions_metric
Setting this value in acreateorupdateoperation fails with aFieldError.IMMUTABLE_FIELDerror. Instead, setprimary_for_goalas
described in theConversion goals guide.
phone_call_duration_seconds
Attempting to set this attribute on a conversion action that isn't for calls
results in aFieldError.VALUE_MUST_BE_UNSETerror.
type
Thetypeattribute is immutable and can only be set when creating a new
conversion.
Updating a conversion action withtypeequal toUNKNOWNresults in aMutateError.MUTATE_NOT_ALLOWEDerror.
value_settings
Thevalue_settingsfor aWEBSITE_CALLorAD_CALLconversion action must
havealways_use_default_valueset totrue. Specifying a value offalsewhen creating or updating this value results in anINVALID_VALUEerror.
view_through_lookback_window_days
Setting this attribute to a value outside of the allowed range results in aRangeError.TOO_LOWorRangeError.TOO_HIGHerror. For most conversion
actions, the allowed range is[1,30].
This attribute cannot be set onAD_CALLorWEBSITE_CALLconversion
actions. Specifying a value results in aVALUE_MUST_BE_UNSETerror.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-09-03 UTC."],[[["\u003cp\u003eConversion tracking must be enabled in your Google Ads conversion account to record conversions.\u003c/p\u003e\n"],["\u003cp\u003eYou can enable conversion tracking by creating at least one conversion action in the Google Ads conversion account.\u003c/p\u003e\n"],["\u003cp\u003eVerify your conversion tracking setup by querying the \u003ccode\u003eCustomer\u003c/code\u003e resource for the \u003ccode\u003eConversionTrackingSetting\u003c/code\u003e.\u003c/p\u003e\n"],["\u003cp\u003eRetrieve existing conversion action details by querying the \u003ccode\u003eConversionAction\u003c/code\u003e resource, ensuring the correct customer ID and conversion action type.\u003c/p\u003e\n"],["\u003cp\u003eCross-account conversion tracking allows access to conversion actions defined by the manager account and those with accrued stats.\u003c/p\u003e\n"]]],[],null,[]]
