Once a conversion has already been reported to Google Ads, you can adjust the conversion at a later point in time in the Google Ads API.
In order to adjust a conversion, you must first have a conversion action set up, and you must also have recorded the conversions that you are about to adjust.
Code example
There are two types of adjustments that can be made:
When you have a Google click ID (GCLID) and conversion date time available, you can adjust a conversion by uploading a
ConversionAdjustment
.You can also adjust a conversion when you have an order ID available instead of a Google click ID and conversion date time.
Both these adjustment types would be uploaded through the
ConversionAdjustmentUploadService
.
Java
private void runExample( GoogleAdsClient googleAdsClient, long customerId, long conversionActionId, String gclid, String adjustmentType, String conversionDateTime, String adjustmentDateTime, @Nullable Float restatementValue) { // Gets the conversion adjustment enum value from the adjustmentType String. ConversionAdjustmentType conversionAdjustmentType = ConversionAdjustmentType.valueOf(adjustmentType); // Associates conversion adjustments with the existing conversion action. // The GCLID should have been uploaded before with a conversion. ConversionAdjustment conversionAdjustment = ConversionAdjustment.newBuilder() .setConversionAction(ResourceNames.conversionAction(customerId, conversionActionId)) .setAdjustmentType(conversionAdjustmentType) .setGclidDateTimePair( GclidDateTimePair.newBuilder() .setGclid(gclid) .setConversionDateTime(conversionDateTime) .build()) .setAdjustmentDateTime(adjustmentDateTime) .build(); // Sets adjusted value for adjustment type RESTATEMENT. if (restatementValue != null && conversionAdjustmentType == ConversionAdjustmentType.RESTATEMENT) { conversionAdjustment = conversionAdjustment.toBuilder() .setRestatementValue( RestatementValue.newBuilder().setAdjustedValue(restatementValue).build()) .build(); } // Creates the conversion upload service client. try (ConversionAdjustmentUploadServiceClient conversionUploadServiceClient = googleAdsClient.getLatestVersion().createConversionAdjustmentUploadServiceClient()) { // Uploads the click conversion. Partial failure should always be set to true. UploadConversionAdjustmentsResponse response = conversionUploadServiceClient.uploadConversionAdjustments( UploadConversionAdjustmentsRequest.newBuilder() .setCustomerId(Long.toString(customerId)) .addConversionAdjustments(conversionAdjustment) // Enables partial failure (must be true). .setPartialFailure(true) .build()); // Prints any partial errors returned. if (response.hasPartialFailureError()) { GoogleAdsFailure googleAdsFailure = ErrorUtils.getInstance().getGoogleAdsFailure(response.getPartialFailureError()); googleAdsFailure .getErrorsList() .forEach(e -> System.out.println("Partial failure occurred: " + e.getMessage())); } else { // Prints the result. ConversionAdjustmentResult result = response.getResults(0); System.out.printf( "Uploaded conversion adjustment of '%s' for Google Click ID '%s'.%n", result.getConversionAction(), result.getGclidDateTimePair().getGclid()); } } }
C#
public void Run(GoogleAdsClient client, long customerId, long conversionActionId, string gclid, string conversionDateTime, string adjustmentDateTime, ConversionAdjustmentType adjustmentType, double? restatementValue) { // Get the ConversionAdjustmentUploadService. ConversionAdjustmentUploadServiceClient conversionAdjustmentUploadService = client.GetService(Services.V15.ConversionAdjustmentUploadService); // Associate conversion adjustments with the existing conversion action. // The GCLID should have been uploaded before with a conversion. ConversionAdjustment conversionAdjustment = new ConversionAdjustment() { ConversionAction = ResourceNames.ConversionAction(customerId, conversionActionId), AdjustmentType = adjustmentType, GclidDateTimePair = new GclidDateTimePair() { Gclid = gclid, ConversionDateTime = conversionDateTime, }, AdjustmentDateTime = adjustmentDateTime, }; // Set adjusted value for adjustment type RESTATEMENT. if (adjustmentType == ConversionAdjustmentType.Restatement) { conversionAdjustment.RestatementValue = new RestatementValue() { AdjustedValue = restatementValue.Value }; } try { // Issue a request to upload the conversion adjustment. UploadConversionAdjustmentsResponse response = conversionAdjustmentUploadService.UploadConversionAdjustments( new UploadConversionAdjustmentsRequest() { CustomerId = customerId.ToString(), ConversionAdjustments = { conversionAdjustment }, PartialFailure = true, ValidateOnly = false }); ConversionAdjustmentResult result = response.Results[0]; // Print the result. Console.WriteLine($"Uploaded conversion adjustment value of" + $" '{result.ConversionAction}' for Google Click ID " + $"'{result.GclidDateTimePair.Gclid}'"); } 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, int $conversionActionId, string $gclid, string $adjustmentType, string $conversionDateTime, string $adjustmentDateTime, float $restatementValue ) { $conversionAdjustmentType = ConversionAdjustmentType::value($adjustmentType); // Associates conversion adjustments with the existing conversion action. // The GCLID should have been uploaded before with a conversion. $conversionAdjustment = new ConversionAdjustment([ 'conversion_action' => ResourceNames::forConversionAction($customerId, $conversionActionId), 'adjustment_type' => $conversionAdjustmentType, 'gclid_date_time_pair' => new GclidDateTimePair([ 'gclid' => $gclid, 'conversion_date_time' => $conversionDateTime ]), 'adjustment_date_time' => $adjustmentDateTime ]); // Sets adjusted value for adjustment type RESTATEMENT. if ( $restatementValue !== null && $conversionAdjustmentType === ConversionAdjustmentType::RESTATEMENT ) { $conversionAdjustment->setRestatementValue(new RestatementValue([ 'adjusted_value' => $restatementValue ])); } // Issues a request to upload the conversion adjustment. $conversionAdjustmentUploadServiceClient = $googleAdsClient->getConversionAdjustmentUploadServiceClient(); $response = $conversionAdjustmentUploadServiceClient->uploadConversionAdjustments( UploadConversionAdjustmentsRequest::build($customerId, [$conversionAdjustment], true) ); // Prints the status message if any partial failure error is returned. // Note: The details of each partial failure error are not printed here, you can refer to // the example HandlePartialFailure.php to learn more. if ($response->hasPartialFailureError()) { printf( "Partial failures occurred: '%s'.%s", $response->getPartialFailureError()->getMessage(), PHP_EOL ); } else { // Prints the result if exists. /** @var ConversionAdjustmentResult $uploadedConversionAdjustment */ $uploadedConversionAdjustment = $response->getResults()[0]; printf( "Uploaded conversion adjustment of '%s' for Google Click ID '%s'.%s", $uploadedConversionAdjustment->getConversionAction(), $uploadedConversionAdjustment->getGclidDateTimePair()->getGclid(), PHP_EOL ); } }
Python
def main( client, customer_id, conversion_action_id, gclid, adjustment_type, conversion_date_time, adjustment_date_time, restatement_value, ): conversion_adjustment_type_enum = client.enums.ConversionAdjustmentTypeEnum # Determine the adjustment type. conversion_adjustment_type = conversion_adjustment_type_enum[ adjustment_type ].value # Associates conversion adjustments with the existing conversion action. # The GCLID should have been uploaded before with a conversion conversion_adjustment = client.get_type("ConversionAdjustment") conversion_action_service = client.get_service("ConversionActionService") conversion_adjustment.conversion_action = ( conversion_action_service.conversion_action_path( customer_id, conversion_action_id ) ) conversion_adjustment.adjustment_type = conversion_adjustment_type conversion_adjustment.adjustment_date_time = adjustment_date_time # Set the Gclid Date conversion_adjustment.gclid_date_time_pair.gclid = gclid conversion_adjustment.gclid_date_time_pair.conversion_date_time = ( conversion_date_time ) # Sets adjusted value for adjustment type RESTATEMENT. if ( restatement_value and conversion_adjustment_type == conversion_adjustment_type_enum.RESTATEMENT.value ): conversion_adjustment.restatement_value.adjusted_value = float( restatement_value ) conversion_adjustment_upload_service = client.get_service( "ConversionAdjustmentUploadService" ) request = client.get_type("UploadConversionAdjustmentsRequest") request.customer_id = customer_id request.conversion_adjustments = [conversion_adjustment] request.partial_failure = True response = ( conversion_adjustment_upload_service.upload_conversion_adjustments( request=request, ) ) conversion_adjustment_result = response.results[0] print( f"Uploaded conversion that occurred at " f'"{conversion_adjustment_result.adjustment_date_time}" ' f"from Gclid " f'"{conversion_adjustment_result.gclid_date_time_pair.gclid}"' f' to "{conversion_adjustment_result.conversion_action}"' )
Ruby
def upload_conversion_adjustment( customer_id, conversion_action_id, gclid, adjustment_type, conversion_date_time, adjustment_date_time, restatement_value ) # GoogleAdsClient will read a config file from # ENV['HOME']/google_ads_config.rb when called without parameters client = Google::Ads::GoogleAds::GoogleAdsClient.new # Associate conversion adjustments with the existing conversion action. # The GCLID should have been uploaded before with a conversion. conversion_adjustment = client.resource.conversion_adjustment do |ca| ca.conversion_action = client.path.conversion_action(customer_id, conversion_action_id) ca.adjustment_type = adjustment_type ca.gclid_date_time_pair = client.resource.gclid_date_time_pair do |gdtp| gdtp.gclid = gclid gdtp.conversion_date_time = conversion_date_time end ca.adjustment_date_time = adjustment_date_time # Set adjusted value for adjustment type RESTATEMENT. if adjustment_type == :RESTATEMENT ca.restatement_value = client.resource.restatement_value do |ra| ra.adjusted_value = restatement_value.to_f end end end # Issue a request to upload the conversion adjustment(s). response = client.service.conversion_adjustment_upload.upload_conversion_adjustments( customer_id: customer_id, # This example shows just one adjustment but you may upload multiple ones. conversion_adjustments: [conversion_adjustment], partial_failure: true ) if response.partial_failure_error.nil? # Process and print all results for multiple adjustments response.results.each do |result| puts "Uploaded conversion adjustment at #{result.adjustment_date_time} " \ "for adjustment #{result.adjustment_type} to #{result.conversion_action}." end else # Print any partial errors returned. failures = client.decode_partial_failure_error(response.partial_failure_error) puts 'Request failed. Failure details:' failures.each do |failure| failure.errors.each do |error| puts "\t#{error.error_code.error_code}: #{error.message}" end end end end
Perl
sub upload_conversion_adjustment { my ($api_client, $customer_id, $conversion_action_id, $gclid, $adjustment_type, $conversion_date_time, $adjustment_date_time, $restatement_value) = @_; # Associate conversion adjustments with the existing conversion action. # The GCLID should have been uploaded before with a conversion. my $conversion_adjustment = Google::Ads::GoogleAds::V15::Services::ConversionAdjustmentUploadService::ConversionAdjustment ->new({ conversionAction => Google::Ads::GoogleAds::V15::Utils::ResourceNames::conversion_action( $customer_id, $conversion_action_id ), adjustmentType => $adjustment_type, gclidDateTimePair => Google::Ads::GoogleAds::V15::Services::ConversionAdjustmentUploadService::GclidDateTimePair ->new({ gclid => $gclid, conversionDateTime => $conversion_date_time } ), adjustmentDateTime => $adjustment_date_time, }); # Set adjusted value for adjustment type RESTATEMENT. $conversion_adjustment->{restatementValue} = Google::Ads::GoogleAds::V15::Services::ConversionAdjustmentUploadService::RestatementValue ->new({ adjustedValue => $restatement_value }) if defined $restatement_value && $adjustment_type eq RESTATEMENT; # Issue a request to upload the conversion adjustment. my $upload_conversion_adjustments_response = $api_client->ConversionAdjustmentUploadService() ->upload_conversion_adjustments({ customerId => $customer_id, conversionAdjustments => [$conversion_adjustment], partialFailure => "true" }); # Print any partial errors returned. if ($upload_conversion_adjustments_response->{partialFailureError}) { printf "Partial error encountered: '%s'.\n", $upload_conversion_adjustments_response->{partialFailureError}{message}; } # Print the result if valid. my $uploaded_conversion_adjustment = $upload_conversion_adjustments_response->{results}[0]; if (%$uploaded_conversion_adjustment) { printf "Uploaded conversion adjustment of the conversion action " . "with resource name '%s' for Google Click ID '%s'.\n", $uploaded_conversion_adjustment->{conversionAction}, $uploaded_conversion_adjustment->{gclidDateTimePair}{gclid}; } return 1; }
Validation rules
Here are some things to keep in mind while adjusting conversions in the API:
Only the account that manages conversion actions is able to upload adjustments. Use the conversion tracking setup instructions to determine which account is managing conversions for your Google Ads account.
Attempting to upload an adjustment using a different account results in a
NO_CONVERSION_ACTION_FOUND
error. This error also occurs if the conversion action of the adjustment is not enabled.Google Ads only supports adjusting conversions for conversion action types of
SALESFORCE
,UPLOAD_CLICKS
, orWEBPAGE
. Attempting to upload an adjustment for a conversion where the conversion action is not one of these types results in anINVALID_CONVERSION_ACTION_TYPE
error.The fields specifying date and time require a timezone which doesn't need to be that of the account. The format of these fields is as
yyyy-mm-dd HH:mm:ss+|-HH:mm
, for example:2022-01-01 19:32:45-05:00
(ignoring daylight saving time) .Wait 4 to 6 hours after creating the conversion action before adjusting its conversions to avoid a
TOO_RECENT_CONVERSION_ACTION
error.The adjustment fails with a
CONVERSION_NOT_FOUND
error if any of these conditions are met:The conversion was never reported.
The conversion was reported less than 24 hours before the adjustment attempt. In some situations, this could lead to a
TOO_RECENT_CONVERSION
error instead.
You must specify the
order_id
in theConversionAdjustment
under any of these conditions:The
type
of the conversion action is equal toWEBPAGE
.The original conversion you are adjusting was assigned an
order_id
.
If you specify the
gclid_date_time_pair
instead, the operation will fail with aConversionAdjustmentUploadError.MISSING_ORDER_ID_FOR_WEBPAGE
orConversionAdjustmentUploadError.CONVERSION_NOT_FOUND
error, respectively.When creating a
ConversionAdjustment
, thepartial_failure
attribute of theUploadConversionAdjustmentsRequest
should always be set totrue
. Follow the partial failures guidelines when handling valid and failed operations simultaneously.You cannot change the
ConversionAction
with an adjustment. Instead, use aRETRACTION
to remove the previous conversion and upload a new conversion with the updatedConversionAction
. The timestamp does not need to be modified. See About conversion adjustments.