Method: customers.uploadClickConversions

Processes the given click conversions.

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

HTTP request

POST https://googleads.googleapis.com/v16/customers/{customerId}:uploadClickConversions

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 
{
  "conversions": [
    {
      object (ClickConversion)
    }
  ],
  "partialFailure": boolean,
  "validateOnly": boolean,
  "debugEnabled": boolean,
  "jobId": integer
}
Fields
conversions[]

object (ClickConversion)

Required. The conversions 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.
debugEnabled

boolean

If true, the API will perform all upload checks and return errors if any are found. If false, it will perform only basic input validation, skip subsequent upload checks, and return success even if no click was found for the provided userIdentifiers.

This setting only affects Enhanced conversions for leads uploads that use userIdentifiers instead of GCLID, GBRAID, or WBRAID. When uploading enhanced conversions for leads, you should upload all conversion events to the API, including those that may not come from Google Ads campaigns. The upload of an event that is not from a Google Ads campaign will result in a CLICK_NOT_FOUND error if this field is set to true. Since these errors are expected for such events, set this field to false so you can confirm your uploads are properly formatted but ignore CLICK_NOT_FOUND errors from all of the conversions that are not from a Google Ads campaign. This will allow you to focus only on errors that you can address.

Default is false.
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 UploadClickConversionsResponse.

Response body

Response message for ConversionUploadService.UploadClickConversions.

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

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

object (Status)

Errors that pertain to conversion failures in the partial failure mode. Returned when all errors occur inside the conversions. If any errors occur outside the conversions (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 (ClickConversionResult)

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

string (int64 format)

Job ID for the upload batch.

Authorization scopes

Requires the following OAuth scope:

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

For more information, see the OAuth 2.0 Overview.

ClickConversion

A click conversion.

JSON representation 
{
  "gbraid": string,
  "wbraid": string,
  "externalAttributionData": {
    object (ExternalAttributionData)
  },
  "customVariables": [
    {
      object (CustomVariable)
    }
  ],
  "cartData": {
    object (CartData)
  },
  "userIdentifiers": [
    {
      object (UserIdentifier)
    }
  ],
  "conversionEnvironment": enum (ConversionEnvironment),
  "consent": {
    object (Consent)
  },
  "gclid": string,
  "conversionAction": string,
  "conversionDateTime": string,
  "conversionValue": number,
  "currencyCode": string,
  "orderId": string
}
Fields
gbraid

string

The click identifier for clicks associated with app conversions and originating from iOS devices starting with iOS14.
wbraid

string

The click identifier for clicks associated with web conversions and originating from iOS devices starting with iOS14.
externalAttributionData

object (ExternalAttributionData)

Additional data about externally attributed conversions. This field is required for conversions with an externally attributed conversion action, but should not be set otherwise.
customVariables[]

object (CustomVariable)

The custom variables associated with this conversion.
cartData

object (CartData)

The cart data associated with this conversion.
userIdentifiers[]

object (UserIdentifier)

The user identifiers associated with this conversion. Only hashedEmail and hashedPhoneNumber are supported for conversion uploads. The maximum number of user identifiers for each conversion is 5.
conversionEnvironment

enum (ConversionEnvironment)

The environment this conversion was recorded on, for example, App or Web.
consent

object (Consent)

The consent setting for the event.
gclid

string

The Google click ID (gclid) associated with this conversion.
conversionAction

string

Resource name of the conversion action associated with this conversion. 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.
conversionDateTime

string

The date time at which the conversion occurred. Must be after the click time. 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".
conversionValue

number

The value of the conversion for the advertiser.
currencyCode

string

Currency associated with the conversion value. This is the ISO 4217 3-character currency code. For example: USD, EUR.
orderId

string

The order ID associated with the conversion. An order id can only be used for one conversion per conversion action.

ExternalAttributionData

Contains additional information about externally attributed conversions.

JSON representation 
{
  "externalAttributionCredit": number,
  "externalAttributionModel": string
}
Fields
externalAttributionCredit

number

Represents the fraction of the conversion that is attributed to the Google Ads click.
externalAttributionModel

string

Specifies the attribution model name.

CartData

Contains additional information about cart data.

JSON representation 
{
  "merchantId": string,
  "feedCountryCode": string,
  "feedLanguageCode": string,
  "localTransactionCost": number,
  "items": [
    {
      object (Item)
    }
  ]
}
Fields
merchantId

string (int64 format)

The Merchant Center ID where the items are uploaded.
feedCountryCode

string

The country code associated with the feed where the items are uploaded.
feedLanguageCode

string

The language code associated with the feed where the items are uploaded.
localTransactionCost

number

Sum of all transaction level discounts, such as free shipping and coupon discounts for the whole cart. The currency code is the same as that in the ClickConversion message.
items[]

object (Item)

Data of the items purchased.

Item

Contains data of the items purchased.

JSON representation 
{
  "productId": string,
  "quantity": integer,
  "unitPrice": number
}
Fields
productId

string

The shopping id of the item. Must be equal to the Merchant Center product identifier.
quantity

integer

Number of items sold.
unitPrice

number

Unit price excluding tax, shipping, and any transaction level discounts. The currency code is the same as that in the ClickConversion message.

ConversionEnvironment

Conversion environment of the uploaded conversion.

Enums
UNSPECIFIED Not specified.
UNKNOWN Used for return value only. Represents value unknown in this version.
APP The conversion was recorded on an app.
WEB The conversion was recorded on a website.

ClickConversionResult

Identifying information for a successfully processed ClickConversion.

JSON representation 
{
  "gbraid": string,
  "wbraid": string,
  "userIdentifiers": [
    {
      object (UserIdentifier)
    }
  ],
  "gclid": string,
  "conversionAction": string,
  "conversionDateTime": string
}
Fields
gbraid

string

The click identifier for clicks associated with app conversions and originating from iOS devices starting with iOS14.
wbraid

string

The click identifier for clicks associated with web conversions and originating from iOS devices starting with iOS14.
userIdentifiers[]

object (UserIdentifier)

The user identifiers associated with this conversion. Only hashedEmail and hashedPhoneNumber are supported for conversion uploads. The maximum number of user identifiers for each conversion is 5.
gclid

string

The Google Click ID (gclid) associated with this conversion.
conversionAction

string

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

string

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