Conversion management

  • Conversions in Google Ads are user actions like purchases or sign-ups that are vital to advertising goals.

  • Conversion tracking provides insights into user actions after viewing or clicking an ad.

  • The Google Ads API allows for programmatic management of the entire conversion management workflow.

  • The guide covers topics including creating, importing, adjusting, monitoring, and grouping conversion actions.

In Google Ads, a conversion is a valuable user action—such as purchasing a product, submitting a lead form, calling your business, or visiting a physical store—that follows an ad interaction. Conversion tracking measures these customer interactions so you can evaluate campaign performance and optimize automated bidding.

The Google Ads API lets you programmatically configure conversion actions, import offline conversion events, enhance or adjust recorded conversions, group actions into bidding and lifecycle goals, and monitor upload diagnostics.

Choose your conversion workflow

Use the following table to identify the ConversionActionType, API service, and implementation guide for your use case:

Task Conversion action type API service or resource Implementation guide
Verify account setup and create a conversion action UPLOAD_CLICKS, WEBPAGE, UPLOAD_CALLS, AD_CALL, WEBSITE_CALL, GOOGLE_PLAY_DOWNLOAD, GOOGLE_PLAY_IN_APP_PURCHASE Customer (ConversionTrackingSetting), ConversionActionService Getting started and Conversion action categories
Import offline click conversions or enhanced conversions for leads UPLOAD_CLICKS ConversionUploadService.UploadClickConversions (or Data Manager API for new integrations) Import offline click conversions
Enhance online conversions (enhanced conversions for web) WEBPAGE ConversionAdjustmentUploadService.UploadConversionAdjustments (ENHANCEMENT) Import online click conversions
Import phone call conversions UPLOAD_CALLS ConversionUploadService.UploadCallConversions Import call conversions
Import store sales transactions STORE_SALES, STORE_SALES_DIRECT_UPLOAD OfflineUserDataJobService (or Data Manager API) Import store sales conversions
Retract or restate recorded conversions UPLOAD_CLICKS, WEBPAGE, SALESFORCE (deprecated) ConversionAdjustmentUploadService.UploadConversionAdjustments (RETRACTION, RESTATEMENT) Adjust conversions after import
Attach custom tag metadata to conversions UPLOAD_CLICKS, UPLOAD_CALLS, WEBPAGE ConversionCustomVariableService Custom conversion variables
Configure bidding goals, lifecycle goals, and value rules Account, campaign, and lifecycle goals CustomerConversionGoalService, CampaignConversionGoalService, CustomConversionGoalService, ConversionGoalCampaignConfigService, GoalService, CampaignGoalConfigService, ConversionValueRuleService Conversion goals, Lifecycle goals, and Conversion value rules
Monitor import health and error diagnostics UPLOAD_CLICKS, WEBPAGE, UPLOAD_CALLS offline_conversion_upload_client_summary, offline_conversion_upload_conversion_action_summary Monitor offline data diagnostics
Query conversion metrics and troubleshoot errors All conversion types GoogleAdsService.SearchStream (customer, campaign, conversion_action) Fetch conversion statistics and Troubleshoot conversion imports

End-to-end conversion lifecycle

A complete conversion management integration in the Google Ads API follows four stages:

  1. Verify account setup and create conversion actions: Query Customer.conversion_tracking_setting to confirm the effective conversion account (google_ads_conversion_customer), verify that conversion tracking is active, configure user consent, and create a ConversionAction with the target ConversionActionType and ConversionActionCategory.
  2. Import conversion events: Stream offline click or call conversions using ConversionUploadService with partial_failure set to true, supplement website conversions with ENHANCEMENT adjustments using ConversionAdjustmentUploadService, or batch-upload store sales using OfflineUserDataJobService.
  3. Adjust and optimize conversions: Retract or restate recorded conversions using ConversionAdjustmentUploadService, attach ConversionCustomVariable metadata, apply conversion value rules, and organize actions into conversion goals and lifecycle goals to control bidding optimization.
  4. Monitor diagnostics and report performance: Query offline_conversion_upload_client_summary and offline_conversion_upload_conversion_action_summary to inspect upload processing status and partial failure alerts. Query the customer or campaign resources (optionally segmented by segments.conversion_action) to compare the metrics.conversions and metrics.all_conversions metrics, or query the conversion_action resource to inspect metrics.all_conversions and last-conversion timestamps.

Quickstart: Verify setup, create actions, and check health

The following examples show the three most common queries and mutations needed to initialize and monitor conversion tracking.

1. Verify conversion tracking settings with GAQL

Before creating a ConversionAction or uploading events, query the customer resource by using GoogleAdsService.SearchStream to determine which account manages conversions (google_ads_conversion_customer), whether customer data terms are accepted, and whether account-level enhanced conversions are turned on (EnhancedConversionsConfig):

SELECT
  customer.conversion_tracking_setting.conversion_tracking_id,
  customer.conversion_tracking_setting.conversion_tracking_status,
  customer.conversion_tracking_setting.cross_account_conversion_tracking_id,
  customer.conversion_tracking_setting.google_ads_conversion_customer,
  customer.conversion_tracking_setting.accepted_customer_data_terms,
  customer.conversion_tracking_setting.enablement_setting,
  customer.conversion_tracking_setting.effective_enablement_setting
FROM customer

Extract the {customer_id} from the customers/{customer_id} resource name returned in google_ads_conversion_customer, and issue all subsequent ConversionActionService and ConversionUploadService requests against that customer ID. For full setup and cross-account hierarchy details, see Getting started.

2. Create a conversion action

Use ConversionActionService.MutateConversionActions to create a ConversionAction. The following example creates an UPLOAD_CLICKS conversion action with custom value and lookback settings:

Java

private void runExample(GoogleAdsClient googleAdsClient, long customerId) {

  // Creates a ConversionAction.
  ConversionAction conversionAction =
      ConversionAction.newBuilder()
          // 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.
          .setName("Earth to Mars Cruises Conversion #" + getPrintableDateTime())
          .setCategory(ConversionActionCategory.DEFAULT)
          .setType(ConversionActionType.WEBPAGE)
          .setStatus(ConversionActionStatus.ENABLED)
          .setViewThroughLookbackWindowDays(15L)
          .setValueSettings(
              ValueSettings.newBuilder()
                  .setDefaultValue(23.41)
                  .setAlwaysUseDefaultValue(true)
                  .build())
          .build();

  // Creates the operation.
  ConversionActionOperation operation =
      ConversionActionOperation.newBuilder().setCreate(conversionAction).build();

  try (ConversionActionServiceClient conversionActionServiceClient =
      googleAdsClient.getLatestVersion().createConversionActionServiceClient()) {
    MutateConversionActionsResponse response =
        conversionActionServiceClient.mutateConversionActions(
            Long.toString(customerId), Collections.singletonList(operation));
    System.out.printf("Added %d conversion actions:%n", response.getResultsCount());
    for (MutateConversionActionResult result : response.getResultsList()) {
      System.out.printf(
          "New conversion action added with resource name: '%s'%n", result.getResourceName());
    }
  }
}

C#

public void Run(GoogleAdsClient client, long customerId)
{
    // Get the ConversionActionService.
    ConversionActionServiceClient conversionActionService =
        client.GetService(Services.V26.ConversionActionService);

    // Note that conversion action names must be unique.
    // If a conversion action already exists with the specified name the create operation
    // will fail with a ConversionAction.DUPLICATE_NAME error.
    string ConversionActionName = "Earth to Mars Cruises Conversion #"
        + ExampleUtilities.GetRandomString();

    // Add a conversion action.
    ConversionAction conversionAction = new ConversionAction()
    {
        Name = ConversionActionName,
        Category = ConversionActionCategory.Default,
        Type = ConversionActionType.Webpage,
        Status = ConversionActionStatus.Enabled,
        ViewThroughLookbackWindowDays = 15,
        ValueSettings = new ConversionAction.Types.ValueSettings()
        {
            DefaultValue = 23.41,
            AlwaysUseDefaultValue = true
        }
    };

    // Create the operation.
    ConversionActionOperation operation = new ConversionActionOperation()
    {
        Create = conversionAction
    };

    try
    {
        // Create the conversion action.
        MutateConversionActionsResponse response =
            conversionActionService.MutateConversionActions(customerId.ToString(),
                    new ConversionActionOperation[] { operation });

        // Display the results.
        foreach (MutateConversionActionResult newConversionAction in response.Results)
        {
            Console.WriteLine($"New conversion action with resource name = " +
                $"'{newConversionAction.ResourceName}' was added.");
        }
    }
    catch (GoogleAdsException e)
    {
        Console.WriteLine("Failure:");
        Console.WriteLine($"Message: {e.Message}");
        Console.WriteLine($"Failure: {e.Failure}");
        Console.WriteLine($"Request ID: {e.RequestId}");
        throw;
    }
}

PHP

    public static function runExample(GoogleAdsClient $googleAdsClient, int $customerId)
    {
        // Creates a conversion action.
        $conversionAction = new ConversionAction(
            [
            // 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.
            'name' => 'Earth to Mars Cruises Conversion #' . Helper::getPrintableDatetime(),
            'category' => ConversionActionCategory::PBDEFAULT,
            'type' => ConversionActionType::WEBPAGE,
            'status' => ConversionActionStatus::ENABLED,
            'view_through_lookback_window_days' => 15,
            'value_settings' => new ValueSettings(
                [
                'default_value' => 23.41,
                'always_use_default_value' => true
                ]
            )
            ]
        );

        // Creates a conversion action operation.
        $conversionActionOperation = new ConversionActionOperation();
        $conversionActionOperation->setCreate($conversionAction);

        // Issues a mutate request to add the conversion action.
        $conversionActionServiceClient = $googleAdsClient->getConversionActionServiceClient();
        $response = $conversionActionServiceClient->mutateConversionActions(
            MutateConversionActionsRequest::build($customerId, [$conversionActionOperation])
        );

        printf("Added %d conversion actions:%s", $response->getResults()->count(), PHP_EOL);

        foreach ($response->getResults() as $addedConversionAction) {
            /**
 * @var ConversionAction $addedConversionAction
*/
            printf(
                "New conversion action added with resource name: '%s'%s",
                $addedConversionAction->getResourceName(),
                PHP_EOL
            );
        }
    }

Python

def main(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.ENABLED
    conversion_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.0
    value_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}".'
    )

Ruby

def add_conversion_action(customer_id)
  # GoogleAdsClient will read a config file from
  # ENV['HOME']/google_ads_config.rb when called without parameters
  client = Google::Ads::GoogleAds::GoogleAdsClient.new


  # Add a conversion action.
  conversion_action = client.resource.conversion_action do |ca|
    ca.name = "Earth to Mars Cruises Conversion #{(Time.new.to_f * 100).to_i}"
    ca.type = :UPLOAD_CLICKS
    ca.category = :DEFAULT
    ca.status = :ENABLED
    ca.view_through_lookback_window_days = 15

    # Create a value settings object.
    ca.value_settings = client.resource.value_settings do |vs|
      vs.default_value = 15
      vs.always_use_default_value = true
    end
  end

  # 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

Perl

sub add_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::V26::Resources::ConversionAction->new({
      name                          => $conversion_action_name,
      category                      => DEFAULT,
      type                          => WEBPAGE,
      status                        => ENABLED,
      viewThroughLookbackWindowDays => 15,
      valueSettings                 =>
        Google::Ads::GoogleAds::V26::Resources::ValueSettings->new({
          defaultValue          => 23.41,
          alwaysUseDefaultValue => "true"
        })});

  # Create a conversion action operation.
  my $conversion_action_operation =
    Google::Ads::GoogleAds::V26::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};

  return 1;
}

curl

REST request

To create the same ConversionAction over REST, send a POST request to ConversionActionService.MutateConversionActions:

POST https://googleads.googleapis.com/v26/customers/{customer_id}/conversionActions:mutate

{
  "operations": [
    {
      "create": {
        "name": "Earth to Mars Cruise Conversion",
        "type": "UPLOAD_CLICKS",
        "category": "DEFAULT",
        "status": "ENABLED",
        "primaryForGoal": true,
        "countingType": "ONE_PER_CLICK",
        "clickThroughLookbackWindowDays": "60",
        "valueSettings": {
          "defaultValue": 23.41,
          "defaultCurrencyCode": "USD",
          "alwaysUseDefaultValue": true
        }
      }
    }
  ]
}

Once your conversion action is ENABLED, import conversion events or enhancements using the workflow for your conversion source (see Import conversion events).

3. Monitor offline conversion upload health

After uploading click conversions, call conversions, or conversion adjustments, query offline_conversion_upload_client_summary to check overall job status, success and pending rates, and error breakdowns across your recent uploads:

SELECT
  offline_conversion_upload_client_summary.client,
  offline_conversion_upload_client_summary.status,
  offline_conversion_upload_client_summary.total_event_count,
  offline_conversion_upload_client_summary.successful_event_count,
  offline_conversion_upload_client_summary.success_rate,
  offline_conversion_upload_client_summary.pending_event_count,
  offline_conversion_upload_client_summary.pending_rate,
  offline_conversion_upload_client_summary.last_upload_date_time,
  offline_conversion_upload_client_summary.alerts
FROM offline_conversion_upload_client_summary

Query offline_conversion_upload_conversion_action_summary for conversion action-level diagnostics (see Monitor offline data diagnostics), and refer to Troubleshoot conversion imports to resolve specific error codes.

Guide directory by lifecycle stage

Explore the full set of conversion management guides organized by lifecycle stage:

1. Account setup and conversion actions

  • Conversion action categories: Select the right conversion source—website (WEBPAGE), phone call (UPLOAD_CALLS, AD_CALL, WEBSITE_CALL), mobile app (GOOGLE_PLAY_DOWNLOAD, GOOGLE_PLAY_IN_APP_PURCHASE, Firebase, SKAdNetwork), Google Analytics 4 (GOOGLE_ANALYTICS_4_CUSTOM, GOOGLE_ANALYTICS_4_PURCHASE), offline (UPLOAD_CLICKS), or physical store (STORE_SALES)—and map it to the corresponding ConversionActionType and API workflow.
  • Getting started: Configure user consent, verify ConversionTrackingSetting, set up cross-account conversion tracking, and create conversion actions using client libraries or REST.

2. Import conversion events

3. Adjust and optimize conversions

4. Monitor, report, and troubleshoot

Next
Conversion action categories