UploadClickConversions

  • The UploadClickConversions RPC processes click conversions using the UploadClickConversionsRequest and returns an UploadClickConversionsResponse.

  • This RPC can throw various errors including AuthenticationError, AuthorizationError, ConversionUploadError, and others.

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

Processes the given click conversions.

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

HTTP request

POST https://googleads.googleapis.com/v21/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,
  "jobId": integer
}
Fields
conversions[]

object (ClickConversion)

Required. The conversions 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 UploadClickConversionsResponse.
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 ConversionUploadService.UploadClickConversions.

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

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

string (int64 format)

Job ID for the upload batch.
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.

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)
  },
  "customerType": enum (ConversionCustomerType),
  "gclid": string,
  "conversionAction": string,
  "conversionDateTime": string,
  "conversionValue": number,
  "currencyCode": string,
  "orderId": string,
  "userIpAddress": string,

  // Union field session_attributes can be only one of the following:
  "sessionAttributesEncoded": string,
  "sessionAttributesKeyValuePairs": {
    object (SessionAttributesKeyValuePairs)
  }
  // End of list of possible types for union field session_attributes.
}
Fields
cartData

object (CartData)

The cart data associated with this conversion.
consent

The consent setting for the event.
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".
conversionEnvironment

enum (ConversionEnvironment)

The environment this conversion was recorded on, for example, App or Web.
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.
customVariables[]

object (CustomVariable)

The custom variables associated with this conversion.
customerType

enum (ConversionCustomerType)

Type of the customer associated with the conversion (new or returning). Accessible only to customers on the allow-list.
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.
gbraid

string

The URL parameter for clicks associated with app conversions.
gclid

string

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

string

The order ID associated with the conversion. An order id can only be used for one conversion per conversion action.
session_attributes. The session attributes for the event. session_attributes can be only one of the following:
sessionAttributesEncoded

string (bytes format)

The session attributes for the event, represented as a base64-encoded JSON string. The content should be generated by Google-provided library. To set session attributes individually, use sessionAttributesKeyValuePairs instead.

A base64-encoded string.
sessionAttributesKeyValuePairs

object (SessionAttributesKeyValuePairs)

The session attributes for the event, represented as key-value pairs.
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.
userIpAddress

string

The IP address of the customer when they arrived on the landing page after an ad click but before a conversion event. This is the IP address of the customer's device, not the advertiser's server. Google Ads does not support IP address matching for end users in the European Economic Area (EEA), United Kingdom (UK), or Switzerland (CH). Add logic to conditionally exclude sharing IP addresses from users from these regions and ensure that you provide users with clear and comprehensive information about the data you collect on your sites, apps, and other properties and get consent where required by law or any applicable Google policies. See the https://support.google.com/google-ads/answer/2998031 page for more details.
wbraid

string

The URL parameter for clicks associated with web conversions.

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
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.
items[]

object (Item)

Data of the items purchased.
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.
merchantId

string (int64 format)

The Merchant Center ID where the items are uploaded.

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
APP The conversion was recorded on an app.
UNKNOWN Used for return value only. Represents value unknown in this version.
UNSPECIFIED Not specified.
WEB The conversion was recorded on a website.

ConversionCustomerType

Enumerates conversion customer types.

Enums
NEW Converting user is new to the advertiser.
RETURNING Converting user is returning to the advertiser. Definition of returning differs among conversion types, such as a second store visit versus a second online purchase.
UNKNOWN The value is unknown in this version.
UNSPECIFIED Not specified.

SessionAttributesKeyValuePairs

Contains session attributes of the conversion, represented as key-value pairs.

JSON representation 
{
  "keyValuePairs": [
    {
      object (SessionAttributeKeyValuePair)
    }
  ]
}
Fields
keyValuePairs[]

object (SessionAttributeKeyValuePair)

Required. The session attributes for the conversion.

SessionAttributeKeyValuePair

Contains one session attribute of the conversion.

JSON representation 
{
  "sessionAttributeKey": string,
  "sessionAttributeValue": string
}
Fields
sessionAttributeKey

string

Required. The name of the session attribute.
sessionAttributeValue

string

Required. The value of the session attribute.

ClickConversionResult

Identifying information for a successfully processed ClickConversion.

JSON representation 
{
  "gbraid": string,
  "wbraid": string,
  "userIdentifiers": [
    {
      object (UserIdentifier)
    }
  ],
  "gclid": string,
  "conversionAction": string,
  "conversionDateTime": string
}
Fields
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".
gbraid

string

The URL parameter for clicks associated with app conversions.
gclid

string

The Google Click ID (gclid) 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.
wbraid

string

The URL parameter for clicks associated with web conversions.
Authorization scopes

Requires the following OAuth scope:

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

For more information, see the OAuth 2.0 Overview.