UploadConversionAdjustments

  • The UploadConversionAdjustments RPC processes conversion adjustments using the UploadConversionAdjustmentsRequest and returns an UploadConversionAdjustmentsResponse.

  • Various errors can be thrown by this RPC, including AuthenticationError, AuthorizationError, and InternalError.

  • This RPC requires the https://www.googleapis.com/auth/adwords OAuth scope for authorization.

Processes the given conversion adjustments.

List of thrown errors: AuthenticationError AuthorizationError HeaderError InternalError PartialFailureError QuotaError RequestError

HTTP request

POST https://googleads.googleapis.com/v20/customers/{customerId}:uploadConversionAdjustments

The URL uses gRPC Transcoding syntax.

Path parameters

Parameters
customerId

string

Required. The ID of the customer performing the upload.

Request body

The request body contains data with the following structure:

JSON representation 
{
  "conversionAdjustments": [
    {
      object (ConversionAdjustment)
    }
  ],
  "partialFailure": boolean,
  "validateOnly": boolean,
  "jobId": integer
}
Fields
conversionAdjustments[]

object (ConversionAdjustment)

Required. The conversion adjustments that are being uploaded.
jobId

integer

Optional. Optional input to set job ID. Must be a non-negative number that is less than 2^31 if provided. If this field is not provided, the API will generate a job ID in the range [2^31, (2^63)-1]. The API will return the value for this request in the jobId field of the UploadConversionAdjustmentsResponse.
partialFailure

boolean

Required. If true, successful operations will be carried out and invalid operations will return errors. If false, all operations will be carried out in one transaction if and only if they are all valid. This should always be set to true. See https://developers.google.com/google-ads/api/docs/best-practices/partial-failures for more information about partial failure.
validateOnly

boolean

If true, the request is validated but not executed. Only errors are returned, not results.

Response body

Response message for ConversionAdjustmentUploadService.UploadConversionAdjustments.

If successful, the response body contains data with the following structure:

JSON representation 
{
  "partialFailureError": {
    object (Status)
  },
  "results": [
    {
      object (ConversionAdjustmentResult)
    }
  ],
  "jobId": string
}
Fields
jobId

string (int64 format)

Job ID for the upload batch.
partialFailureError

object (Status)

Errors that pertain to conversion adjustment failures in the partial failure mode. Returned when all errors occur inside the adjustments. If any errors occur outside the adjustments (for example, auth errors), we return an RPC level error. See https://developers.google.com/google-ads/api/docs/best-practices/partial-failures for more information about partial failure.
results[]

object (ConversionAdjustmentResult)

Returned for successfully processed conversion adjustments. Proto will be empty for rows that received an error. Results are not returned when validateOnly is true.

ConversionAdjustment

A conversion adjustment.

JSON representation 
{
  "gclidDateTimePair": {
    object (GclidDateTimePair)
  },
  "adjustmentType": enum (ConversionAdjustmentType),
  "restatementValue": {
    object (RestatementValue)
  },
  "userIdentifiers": [
    {
      object (UserIdentifier)
    }
  ],
  "orderId": string,
  "conversionAction": string,
  "adjustmentDateTime": string,
  "userAgent": string
}
Fields
adjustmentDateTime

string

The date time at which the adjustment occurred. Must be after the conversionDateTime. The timezone must be specified. The format is "yyyy-mm-dd hh:mm:ss+|-hh:mm", for example, "2019-01-01 12:32:45-08:00".
adjustmentType

enum (ConversionAdjustmentType)

The adjustment type.
conversionAction

string

Resource name of the conversion action associated with this conversion adjustment. Note: Although this resource name consists of a customer id and a conversion action id, validation will ignore the customer id and use the conversion action id as the sole identifier of the conversion action.
gclidDateTimePair

object (GclidDateTimePair)

For adjustments, uniquely identifies a conversion that was reported without an order ID specified. If the adjustmentType is ENHANCEMENT, this value is optional but may be set in addition to the orderId.
orderId

string

The order ID of the conversion to be adjusted. If the conversion was reported with an order ID specified, that order ID must be used as the identifier here. The order ID is required for enhancements.
restatementValue

object (RestatementValue)

Information needed to restate the conversion's value. Required for restatements. Should not be supplied for retractions. An error will be returned if provided for a retraction. NOTE: If you want to upload a second restatement with a different adjusted value, it must have a new, more recent, adjustment occurrence time. Otherwise, it will be treated as a duplicate of the previous restatement and ignored.
userAgent

string

The user agent to enhance the original conversion. This can be found in your user's HTTP request header when they convert on your web page. Example, "Mozilla/5.0 (iPhone; CPU iPhone OS 12_2 like Mac OS X)". User agent can only be specified in enhancements with user identifiers. This should match the user agent of the request that sent the original conversion so the conversion and its enhancement are either both attributed as same-device or both attributed as cross-device.
userIdentifiers[]

object (UserIdentifier)

The user identifiers to enhance the original conversion. ConversionAdjustmentUploadService only accepts user identifiers in enhancements. The maximum number of user identifiers for each enhancement is 5.

GclidDateTimePair

Uniquely identifies a conversion that was reported without an order ID specified.

JSON representation 
{
  "gclid": string,
  "conversionDateTime": string
}
Fields
conversionDateTime

string

The date time at which the original conversion for this adjustment occurred. The timezone must be specified. The format is "yyyy-mm-dd hh:mm:ss+|-hh:mm", for example, "2019-01-01 12:32:45-08:00".
gclid

string

Google click ID (gclid) associated with the original conversion for this adjustment.

ConversionAdjustmentType

The different actions advertisers can take to adjust the conversions that they already reported. Retractions negate a conversion. Restatements change the value of a conversion.

Enums
ENHANCEMENT Supplements an existing conversion with provided user identifiers and user agent, which can be used by Google to enhance the conversion count.
RESTATEMENT Changes the value of a conversion.
RETRACTION Negates a conversion so that its total value and count are both zero.
UNKNOWN Represents value unknown in this version.
UNSPECIFIED Not specified.

RestatementValue

Contains information needed to restate a conversion's value.

JSON representation 
{
  "adjustedValue": number,
  "currencyCode": string
}
Fields
adjustedValue

number

The restated conversion value. This is the value of the conversion after restatement. For example, to change the value of a conversion from 100 to 70, an adjusted value of 70 should be reported. NOTE: If you want to upload a second restatement with a different adjusted value, it must have a new, more recent, adjustment occurrence time. Otherwise, it will be treated as a duplicate of the previous restatement and ignored.
currencyCode

string

The currency of the restated value. If not provided, then the default currency from the conversion action is used, and if that is not set then the account currency is used. This is the ISO 4217 3-character currency code for example, USD or EUR.

ConversionAdjustmentResult

Information identifying a successfully processed ConversionAdjustment.

JSON representation 
{
  "gclidDateTimePair": {
    object (GclidDateTimePair)
  },
  "orderId": string,
  "adjustmentType": enum (ConversionAdjustmentType),
  "conversionAction": string,
  "adjustmentDateTime": string
}
Fields
adjustmentDateTime

string

The date time at which the adjustment occurred. The format is "yyyy-mm-dd hh:mm:ss+|-hh:mm", for example, "2019-01-01 12:32:45-08:00".
adjustmentType

enum (ConversionAdjustmentType)

The adjustment type.
conversionAction

string

Resource name of the conversion action associated with this conversion adjustment.
gclidDateTimePair

object (GclidDateTimePair)

The gclid and conversion date time of the conversion.
orderId

string

The order ID of the conversion to be adjusted.
Authorization scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/adwords

For more information, see the OAuth 2.0 Overview.