Google Ads Enhanced Conversions: the 2026 setup manual

Create the OAuth client and capture a refresh token

Google Ads API uploads use OAuth, not a static account key. Create an OAuth client in Google Cloud, request the Ads scope, complete the consent screen with the Google user that owns or manages the Ads account, and store the refresh token in your secrets manager. Treat the token as production infrastructure because failed refreshes stop conversion uploads silently until monitoring catches them.

GET https://accounts.google.com/o/oauth2/v2/auth
  ?client_id=GOOGLE_CLIENT_ID
  &redirect_uri=https://app.example.com/oauth/google/callback
  &response_type=code
  &scope=https://www.googleapis.com/auth/adwords
  &access_type=offline
  &prompt=consent

POST https://oauth2.googleapis.com/token
content-type: application/x-www-form-urlencoded

code=AUTH_CODE&
client_id=GOOGLE_CLIENT_ID&
client_secret=GOOGLE_CLIENT_SECRET&
redirect_uri=https://app.example.com/oauth/google/callback&
grant_type=authorization_code

Resolve the customer ID and conversion action resource

Use the customer account that owns the conversion action, not just the manager account you log into every day. Store customer IDs without hyphens and store conversion actions as resource names. That gives every upload job a stable target and avoids the common mistake of sending a valid conversion to the wrong child account.

customer_id = "1234567890"
conversion_action_id = "987654321"

conversion_action =
  "customers/1234567890/conversionActions/987654321"

Call the conversion upload endpoint

Batch uploads should be small enough to retry safely and large enough to avoid noisy per-order API calls. Use partial failure mode so one bad identifier does not block the whole batch. For documentation and internal runbooks, many teams describe this as posting to /customers/{id}/conversionUploads:upload; in the current REST API this maps to the customer uploadClickConversions method.

POST https://googleads.googleapis.com/v22/customers/{customer_id}:uploadClickConversions
developer-token: GOOGLE_ADS_DEVELOPER_TOKEN
login-customer-id: MANAGER_CUSTOMER_ID
authorization: Bearer ACCESS_TOKEN
content-type: application/json

{
  "partialFailure": true,
  "validateOnly": false,
  "debugEnabled": false,
  "conversions": []
}

Send the base conversion payload

The first payload should be boring: one conversion action, one timestamp, one value, one currency, one order ID, one click identifier, and explicit consent. Get this accepted before adding enhanced identifiers. A minimal accepted payload proves account access, conversion action ownership, timestamp formatting, and click ID capture.

{
  "partialFailure": true,
  "conversions": [
    {
      "conversionAction": "customers/1234567890/conversionActions/987654321",
      "conversionDateTime": "2026-04-23 14:31:09+02:00",
      "conversionValue": 129.95,
      "currencyCode": "EUR",
      "orderId": "ORDER-10492",
      "gclid": "EAIaIQobChMI...",
      "conversionEnvironment": "WEB",
      "consent": {
        "adUserData": "GRANTED",
        "adPersonalization": "GRANTED"
      }
    }
  ]
}

Add enhanced conversion identifiers

Enhanced Conversions depends on normalized and SHA-256 hashed user data. Normalize before hashing: lowercase emails, trim whitespace, remove separators from phone numbers, and format phone numbers consistently. Do not hash nulls, placeholders, or values collected without the right consent basis. Send multiple identifiers when you have them because match quality usually improves when email and phone arrive together.

import crypto from "node:crypto";

function sha256(value: string) {
  return crypto
    .createHash("sha256")
    .update(value.trim().toLowerCase())
    .digest("hex");
}

const userIdentifiers = [
  { hashedEmail: sha256("customer@example.com") },
  { hashedPhoneNumber: sha256("+491701234567") },
];

Choose click ID first, enhanced identifiers as fallback

For web purchases, click identifiers remain the cleanest attribution key. Use GCLID when present, GBRAID for iOS app-originated click paths, and WBRAID for iOS web-originated click paths. When no click ID survives into the order, upload enhanced conversion identifiers so Google can attempt a user match. Keep the logic explicit, and never invent a click ID from session data.

const conversion = {
  conversionAction,
  conversionDateTime: order.paidAtGoogleAdsFormat,
  conversionValue: order.total,
  currencyCode: order.currency,
  orderId: order.id,
  conversionEnvironment: "WEB",
  consent: {
    adUserData: order.consent.ad_user_data,
    adPersonalization: order.consent.ad_personalization,
  },
};

if (order.gclid) conversion.gclid = order.gclid;
else if (order.gbraid) conversion.gbraid = order.gbraid;
else if (order.wbraid) conversion.wbraid = order.wbraid;
else conversion.userIdentifiers = userIdentifiers;

Do Enhanced Conversions replace the Google tag?

Not always. Enhanced Conversions for web commonly starts with the Google tag or GTM sending a conversion and order ID, then the API enhances that conversion with hashed user data. Server-side uploads are useful when the final conversion source is backend checkout, CRM, subscription billing, or a lead qualification system.

Should I upload every order or only Google Ads orders?

For enhanced conversion fallback workflows, many teams upload all eligible conversion events and let Google match what belongs to Google Ads traffic. Keep consent filtering in place and decide whether debug mode should surface expected CLICK_NOT_FOUND cases.

Can I send both GCLID and hashed email?

Yes. For web conversions, a click ID plus enhanced user identifiers is typically stronger than either signal alone. The important part is that the data describes the same conversion and was collected with appropriate consent.

How fast do diagnostics update?

Uploads return API acceptance quickly, but Google Ads diagnostics and reporting can lag. Evaluate status over at least a full day of normal traffic, and longer when conversion volume is low.

What timestamp should I use for delayed payments?

Use the time the conversion actually occurred according to your business definition. For ecommerce, that is usually paid order time, not first checkout start. Keep the timezone explicit so Google does not compare the conversion against the click incorrectly.

What consent values should I send?

Map your CMP or Consent Mode v2 state into ad_user_data and ad_personalization. When consent is denied, do not send personal identifiers and send the denied state so upload behavior matches the user choice.