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.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/v8/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
}
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.

Response body

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

Response message for ConversionUploadService.UploadClickConversions.

JSON representation
{
  "partialFailureError": {
    object (Status)
  },
  "results": [
    {
      object (ClickConversionResult)
    }
  ]
}
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 (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 (ClickConversionResult)

Returned for successfully processed conversions. 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.

ClickConversion

A click conversion.

JSON representation
{
  "externalAttributionData": {
    object (ExternalAttributionData)
  },
  "customVariables": [
    {
      object (CustomVariable)
    }
  ],
  "cartData": {
    object (CartData)
  },
  "userIdentifiers": [
    {
      object (UserIdentifier)
    }
  ],
  "gclid": string,
  "conversionAction": string,
  "conversionDateTime": string,
  "conversionValue": number,
  "currencyCode": string,
  "orderId": string
}
Fields
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.

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", e.g. “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

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.

ClickConversionResult

Identifying information for a successfully processed ClickConversion.

JSON representation
{
  "userIdentifiers": [
    {
      object (UserIdentifier)
    }
  ],
  "gclid": string,
  "conversionAction": string,
  "conversionDateTime": string
}
Fields
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", e.g. “2019-01-01 12:32:45-08:00”.