Caution: You are viewing documentation for the API's REST interface. Most of our official client libraries use gRPC. See the REST Introduction for details.

Method: customers.uploadConversionAdjustments

Processes the given conversion adjustments.

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

HTTP request

POST https://googleads.googleapis.com/v8/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
}
Fields
conversionAdjustments[]

object (ConversionAdjustment)

Required. The conversion adjustments that are being uploaded.

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

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

Response message for ConversionAdjustmentUploadService.UploadConversionAdjustments.

JSON representation
{
  "partialFailureError": {
    object (Status)
  },
  "results": [
    {
      object (ConversionAdjustmentResult)
    }
  ]
}
Fields
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 (e.g. 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.

Authorization Scopes

Requires the following OAuth scope:

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

For more information, see the OAuth 2.0 Overview.

ConversionAdjustment

A conversion adjustment.

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

  // Union field conversion_identifier can be only one of the following:
  "gclidDateTimePair": {
    object (GclidDateTimePair)
  },
  "orderId": string
  // End of list of possible types for union field conversion_identifier.
}
Fields
adjustmentType

enum (ConversionAdjustmentType)

The adjustment type.

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.

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.

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.

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", e.g. "2019-01-01 12:32:45-08:00".

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.

Union field conversion_identifier. Identifies the conversion to be adjusted. conversion_identifier can be only one of the following:
gclidDateTimePair

object (GclidDateTimePair)

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

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.

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

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 e.g. USD or EUR.

GclidDateTimePair

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

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

string

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

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", e.g. "2019-01-01 12:32:45-08:00".

ConversionAdjustmentResult

Information identifying a successfully processed ConversionAdjustment.

JSON representation
{
  "adjustmentType": enum (ConversionAdjustmentType),
  "conversionAction": string,
  "adjustmentDateTime": string,

  // Union field conversion_identifier can be only one of the following:
  "gclidDateTimePair": {
    object (GclidDateTimePair)
  },
  "orderId": string
  // End of list of possible types for union field conversion_identifier.
}
Fields
adjustmentType

enum (ConversionAdjustmentType)

The adjustment type.

conversionAction

string

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

adjustmentDateTime

string

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

Union field conversion_identifier. Identifies the conversion that was adjusted. conversion_identifier can be only one of the following:
gclidDateTimePair

object (GclidDateTimePair)

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

orderId

string

The order ID of the conversion that was adjusted.