Overview
This node uploads click conversion events to Google Ads, enabling advertisers to track and optimize their ad campaigns based on user actions. It supports both regular Google Ads accounts and manager (MCC) accounts managing multiple clients. The node allows sending detailed conversion data including conversion action, timestamp, value, currency, order ID, and user identification via various methods such as Google Click ID (GCLID), iOS app/web install identifiers (GBRAID/WBRAID), or enhanced conversions using hashed user data.
Typical use cases include:
- Reporting offline conversions back to Google Ads for accurate attribution.
- Uploading app install or web-to-app conversion events.
- Using enhanced conversions to improve match rates by sending hashed user information.
- Batch processing large volumes of conversions efficiently.
Example: After a purchase on an e-commerce site, the node can upload the transaction details along with the GCLID to Google Ads to attribute the sale to the correct ad click.
Properties
| Name | Meaning |
|---|---|
| Operation | The operation to perform; here only "Upload Click Conversion" is supported. |
| Account Type | Select account type: "Regular Google Ads Account" (direct account) or "Manager Account (MCC)" (manages multiple client accounts). |
| Managed Account | For manager accounts, select the managed client account to upload conversions to (by list or by customer ID). |
| Conversion Action | The conversion action resource from Google Ads to associate the conversion with (select from list or enter full resource name/ID). |
| Conversion Date Time | Date and time when the conversion occurred. Accepts current time or formatted string (e.g., 2024-01-15 14:30:00+00:00). |
| Conversion Value | Numeric value of the conversion (optional). |
| Currency Code | Three-letter ISO 4217 currency code for the conversion value (default "USD"). |
| Order ID | Unique transaction/order identifier (optional but recommended). |
| Identification Method | Method to identify the user who converted: GCLID, GBRAID (iOS app install), WBRAID (iOS web-to-app), or Enhanced Conversions (hashed user data). |
| GCLID | Google Click ID from the ad click (required if identification method is GCLID). |
| GBRAID | GBRAID for iOS app install conversions (required if identification method is GBRAID). |
| WBRAID | WBRAID for iOS web-to-app conversions (required if identification method is WBRAID). |
| User email address (will be hashed automatically, required if identification method is Enhanced Conversions). | |
| Phone Number | User phone number in E.164 format (hashed automatically, optional for Enhanced Conversions). |
| First Name | User first name (hashed automatically, optional for Enhanced Conversions). |
| Last Name | User last name (hashed automatically, optional for Enhanced Conversions). |
| Street Address | User street address (hashed automatically, optional for Enhanced Conversions). |
| City | User city (hashed automatically, optional for Enhanced Conversions). |
| State/Region | User state or region (hashed automatically, optional for Enhanced Conversions). |
| Postal Code | User postal/ZIP code (hashed automatically, optional for Enhanced Conversions). |
| Country Code | Two-letter ISO 3166-1 alpha-2 country code (hashed automatically, optional for Enhanced Conversions). |
| Ad User Data Consent | User consent status for ad user data usage (GRANTED, DENIED, UNKNOWN) - required for compliance in European Economic Area (EEA). |
| Ad Personalization Consent | User consent status for ad personalization (GRANTED, DENIED, UNKNOWN) - required for compliance in EEA. |
| Validate Only | If true, only validate the conversion data without uploading it. |
| Debug Mode | Enable detailed logging and response data for debugging purposes. |
| Enable Batch Processing | Enable processing multiple conversions in batches for better performance. |
| Batch Size | Number of conversions per batch (1 to 2000). |
| Batch Processing Mode | Error handling mode during batch processing: Fail on first error, Continue on errors, or Partial failure mode (recommended). |
| Show Progress | Log progress information during batch processing. |
Output
The node outputs an array of JSON objects representing the result of each conversion upload attempt. Each output item includes:
success: Boolean indicating if the conversion was successfully uploaded or validated.message: Status message describing the outcome.operation: The operation performed ("uploadClickConversion").conversion: The payload sent to Google Ads for that conversion.response: The raw API response from Google Ads.itemIndex: Index of the input item processed.error(if any): Error message if the upload failed.errorType,httpCode,apiErrorCode: Additional error metadata.batchNumber,batchPosition(if batch processing): Position info within batch.debugInfo(if debug mode enabled): Detailed debug data including request headers and timestamps.
If batch processing is enabled, the output contains results for each item in the batch, including partial failures with detailed error extraction.
The node does not output binary data.
Dependencies
- Requires a valid Google Ads OAuth2 credential with:
- Developer token
- Customer ID (Google Ads account ID)
- Google Ads API v17 endpoint (
https://googleads.googleapis.com/v17) - Proper permissions and access to the target Google Ads account or managed accounts.
- For manager accounts, selection of a managed client account is mandatory.
- Network connectivity to Google Ads API.
- Optional environment configuration for OAuth2 credentials in n8n.
Troubleshooting
Common Issues
- Authentication Errors: Occur if OAuth2 token expired, revoked, or invalid developer token.
- Permission Denied (403): Insufficient permissions for the selected account or developer token not approved.
- Invalid Customer ID: Customer ID missing, malformed, or containing non-digit characters.
- Conversion Action Not Found or Disabled: Conversion action must exist and be enabled in Google Ads.
- Date Validation Errors: Conversion date cannot be in the future and should be in proper format.
- Missing Required Fields: Depending on identification method, required fields like GCLID or user identifiers may be missing.
- Rate Limits (429): Too many requests; node retries with exponential backoff.
- Batch Processing Errors: Can fail partially depending on error handling mode.
Error Messages & Resolutions
- Authentication Error: Re-authenticate Google Ads OAuth2 credentials; check token validity.
- Validation Error: Check required parameters like conversion action, date/time, and user IDs.
- API Error 400 (Bad Request): Review parameter formats and values; enable debug mode for details.
- Rate Limit Error: Slow down requests or reduce batch size.
- Invalid URL Error: Usually caused by malformed customer ID; verify account type and IDs.
- Permission Issue Diagnostics: Use debug mode to get detailed logs; ensure developer token is approved and account access is correct.