Google Ads Conversions API

The Google Ads Conversions API is Google's server-to-server mechanism for importing conversion data — purchase events, leads, offline sales — directly into Google Ads from a retailer's own backend, bypassing the browser entirely. It is the foundation for Enhanced Conversions, Server-Side Tagging via sGTM, and (from 2025) the Data Manager API. The primary practical motivation: client-side tracking via gtag.js or GTM captures only approximately 80% of conversions (as-of 2025), with the remainder lost to ad blockers, browser privacy restrictions, checkout page script limitations, and users closing the browser before the tag fires. (fiveninestrategy.com, 2025-12-12; profitmetrics.io, undated)

Firewall: every claim is what a source reports. See ../../CONTEXT.md Rule 1.

---

How GCLID-based conversion import works

When a user clicks a Google Ad, Google appends a GCLID (Google Click Identifier) to the landing page URL as a query parameter. This identifier is the primary key for attributing a subsequent server-side conversion back to the originating ad click. The retailer's system must:

1. Capture the GCLID at click time — typically via a first-party cookie written by the Conversion Linker tag in sGTM (the FPGCLAW cookie). The Conversion Linker fires on every event, not only page_view, to set the cookie as early as possible. (Stape, 2024-08-12)
2. Store the GCLID through the conversion journey — in a server-side session, database record, or first-party cookie tied to the customer identity.
3. Upload a conversion payload via the Google Ads API UploadClickConversions method, including at minimum: GCLID/GBRAID/WBRAID, conversion_date_time (with timezone), and a conversion action resource name. Optional fields: hashed user identifiers (email, phone), conversion_value, currency_code, order_id. (fiveninestrategy.com, 2025-12-12)

iOS click identifiers

In response to Apple's App Tracking Transparency restrictions, Google created two iOS-specific variants alongside GCLID:

• GBRAID — for app conversions originating from iOS
• WBRAID — for web conversions originating from iOS

All three appear as URL query parameters after an ad click. (fiveninestrategy.com, 2025-12-12)

From October 3, 2025, Google lifted the previous restriction that prevented sending both GCLID and GBRAID in a single ClickConversion payload; previously this produced a FieldError.VALUE_MUST_BE_UNSET partial failure. (ppc.land, 2025-07 announcement, effective 2025-10-03)

---

Enhanced Conversions — hashed PII matching

Enhanced Conversions is the mechanism layered on top of GCLID-based import that improves attribution by sending SHA-256 hashed customer identifiers (email address, phone number, name, address) alongside or instead of a GCLID. Google matches the hashed data against hashed identifiers of signed-in Google accounts, recovering attribution for cross-device journeys and cookie-expired sessions where the GCLID alone is insufficient.

Raw PII is never transmitted to Google; all matching is done on hashed values. (trackbee.io, 2026-06-27)

Two variants:

• Enhanced Conversions for Web — conversions completing on the website; most relevant for ecommerce purchase events
• Enhanced Conversions for Leads — offline conversions initiated by a form submission where the actual sale closes later; relevant for B2B/high-ticket retail

Minimum identifier: email address (most valuable). Phone number is second most valuable. Name, city, street address additionally improve match rates. (Stape, 2024-08-12)

When to enable: Enhanced Conversions should be activated only for events where user data is reliably present — purchase and lead events. Enabling it for add-to-cart or product page events produces errors when no user data is available (not logged-in users). (Stape, 2025-06-27)

April 2026 unification (as-of 2026-04)

Starting April 2026, Google collapsed Enhanced Conversions for Web and for Leads into a single account-level toggle, eliminating the requirement to choose a single data ingestion channel. From April 2026, Google Ads simultaneously accepts user-provided data from website tags, Data Manager API, and direct API connections in the same account. (ppc.land, 2026-04-10; Stape, 2025-06-27)

Consent dependency (EEA)

For users in the EEA, Enhanced Conversions require specific Google Consent Mode v2 signals to fire:

• ad_user_data — controls whether Google processes user data for advertising
• ad_personalization — controls remarketing targeting

If ad_user_data is not granted, EC submissions are silently dropped for EEA users. (Stape, 2024-08-12; measuremindsgroup.com via Enhanced Conversions page)

---

Implementation paths

Three implementation paths exist for sending conversions to Google Ads (fiveninestrategy.com, 2025-12-12; Stape, 2024-08-12):

Path	Description	Trade-offs
gtag.js (client-side)	JavaScript tag fires in user's browser	Easiest; subject to ad blockers, ITP, script failures
sGTM Offline Conversion tag	Server GTM container calls the Google Ads API via OAuth	Low complexity if sGTM already deployed; native Google Ads sGTM tag only works via GA4 requests — Data Tag/Data Client cannot be used for the native tag (Stape, 2025-06-27)
Direct Google Ads API	Server calls UploadClickConversions with OAuth 2.0	Maximum control; requires Developer Token + OAuth setup; recommended when a CDP supplies unified customer profiles

API authentication requirements

• Developer Token — obtained via Google Ads Manager account → API Center; approval can take up to 48 hours (as-of 2025)
• OAuth 2.0 credentials — client ID, client secret, refresh token
• Google Ads Customer ID

The API endpoint (as-of API v17, volatile): POST https://googleads.googleapis.com/v17/customers/<CID>:uploadClickConversions (fiveninestrategy.com, 2025-12-12)

Recommended: partialFailure: true to prevent a single bad record from failing the whole batch; validateOnly: true for testing. (fiveninestrategy.com, 2025-12-12)

Ecommerce server-side pattern (Shopify / WooCommerce)

The standard recommended pattern for Shopify/WooCommerce: (trackbee.io, 2026-06-27; Stape, 2025-06-27)

1. Capture GCLID in a first-party cookie at click time (via sGTM Conversion Linker)
2. Pass the GCLID through checkout to the order record in the backend
3. On purchase confirmation, send a server-side EC payload via the Conversions API or sGTM tag, combining the stored GCLID with SHA-256 hashed email from the order

Server-side collection bypasses Shopify's checkout page restrictions on custom JavaScript execution that limit what client-side scripts can access. (trackbee.io, 2026-06-27)

Stape's Shopify app sends a webhook directly to server GTM on purchase events — this cannot be blocked by ad blockers at all. (Stape, 2025-06-27)

---

GA4 Measurement Protocol — maintenance mode (as-of 2025-12)

The GA4 Measurement Protocol is a raw HTTP ingestion mechanism for sending events directly to a GA4 property (requires an API secret + measurement_id). It was designed to supplement, not replace, automatic collection via gtag/GTM/Firebase; the documentation states gtag/GTM must also be in place because the Measurement Protocol alone does not establish complete session context. (ppc.land, 2026-06-06)

As of December 2025, the GA4 Measurement Protocol was placed in maintenance mode. The official documentation banner reads: "The Measurement protocol is now in maintenance mode. No future enhancements are planned. Upgrade to the Data Manager API to future-proof your integration." No shutdown date has been announced; existing integrations continue to function. GA4 Measurement Protocol events carry no demographic payload — demographics/interests data require Google Signals (browser JavaScript + cookie consent). (ppc.land, 2026-06-06)

---

Data Manager API — unified ingestion layer (GA October 2025)

Google launched the Data Manager API as the strategic successor to both the GA4 Measurement Protocol and the legacy UploadClickConversions method. Key differences from the legacy API (ppc.land, 2026-06-06):

1. Unified data model across Google Ads, GA4, and Display & Video 360
2. Encryption via XChaCha20-Poly1305
3. Single request, multiple destinations — one call can target GA4 + Google Ads simultaneously
4. No API secret required — authentication uses OAuth 2.0 with the datamanager scope

General availability: October 2025 with eleven launch partners including Hightouch, Tealium, Treasure Data, Zapier. (ppc.land, 2026-06-06)

Version 1.6 (May 7, 2026) added native support for uploading store sales conversions and expanded event ingestion for GA4 across web and app data streams. (ppc.land, 2026-06-06)

Rate limits (as-of 2026-06-06, volatile): 100,000 requests/day per Google Cloud project, 300 requests/minute; up to 10,000 audience members or 2,000 conversion events per request; up to 10 user identifiers per record.

Allowlist status: As of June 2026, the Data Manager API is still behind an allowlist — some teams cannot yet migrate. (ppc.land, 2026-06-06)

---

Critical 2025–2026 deprecation timeline

Date	Change
Oct 3, 2025	Dual GCLID+GBRAID in single ClickConversion payload permitted
Dec 2025	GA4 Measurement Protocol enters maintenance mode
Dec 9, 2025	Data Manager API launches (GA October 2025, announced)
Feb 2, 2026	IP address/session attribute fields blocked in API for new tokens
Apr 1, 2026	Customer Match via OfflineUserDataJobService / UserDataService retired; Data Manager API required
Apr 2026	EC unified into single toggle; multi-source ingestion enabled
Jun 15, 2026	UploadClickConversions blocked for new adopters (accounts with no prior usage window Dec 2025–May 2026)

(Sources: ppc.land 2026-06-06; groas.com 2026-06-12; ppcnewsfeed.com 2025)

---

Benchmarks (as-of 2025–2026)

Metric	Value	Source
Client-side (gtag.js) conversion capture rate	~80%	fiveninestrategy.com (2025-12-12); profitmetrics.io (undated)
Enhanced Conversions lift on Search	+5% attributed conversions	Google via trackbee.io (2026-06-27)
Enhanced Conversions lift on YouTube ads	+17% attributed conversions	Google via trackbee.io (2026-06-27)
Server-side vs client-side lift	+10–30% measured conversions	Tracklution, Stape guides (2024–2025)
Server-side offline import recovery	+12% conversions vs global tag	profitmetrics.io (undated, cited in Stape 2025-06-27)
Match rate target	>80% (visible in Diagnostics tab)	fiveninestrategy.com (2025-12-12)
Enhanced Conversions for Leads median lift	+10% attributed conversions	ppcmastery.com (2025)
EC adoption rate (mid-sized ecommerce, 2024)	~32% had activated EC (as-of 2024)	Shopify blog (2024)

[!unverified] The vendor case study from TrackBee (HoneyBalm, Shopify DTC): ROAS doubled, revenue grew 123% in 3 months, CPM fell 60% after server-side EC. No independent verification. (trackbee.io, 2026-06-27)

---

Common pitfalls

GCLID expiry (90-day window)

GCLIDs expire after 90 days; conversions uploaded after that window are silently dropped and never appear in stats. B2B practitioners with long sales cycles are particularly exposed. (support.google.com; ppcnewsfeed.com, 2025)

Enhanced Conversions for Leads has a shorter 63-day upload window — a lesser-known difference that catches practitioners off-guard. (ppcnewsfeed.com, 2025)

CLICK_NOT_FOUND error

The most commonly reported API upload error. Root causes: GCLID expired (>90 days), no conversion action existed at click time, or auto-tagging was disabled. Some practitioners report 100% CLICK_NOT_FOUND rates when the conversion action was created after the clicks being imported. (whatconverts.com, 2024; developer forums)

Partial failure response ambiguity

The partial_failure_error field can be empty (no details) even when partial failures occurred, causing code to enter error-handling branches on empty responses and creating false alarms in monitoring pipelines. (Google Groups/adwords-api, 2024)

GCLID vs PII priority conflict

When both a GCLID and user identifiers (hashed email/phone) are included in the same ClickConversion payload, Google prioritizes the GCLID and ignores user identifiers. Practitioners report that omitting the GCLID and sending only hashed PII sometimes resolves match failures for campaigns relying on cross-device matching. (Google Groups/adwords-api, 2024)

Deduplication requires transaction_id

Google Ads does not deduplicate conversions between web and server containers unless a transaction_id (e.g. order ID) is present. Without it, running both client-side and server-side tracking for the same conversion action causes duplicate events. Misconfigured deduplication can inflate conversion counts. (Stape, 2025-06-27)

Safari GCLID removal (as-of 2025-09)

Apple's ITP extended GCLID stripping to standard (non-private) Safari browsing sessions from approximately September 2025. Safari holds ~20% of global browser share, creating a potential 20% attribution gap without mitigation. Safari preserves UTM parameters (aggregate-level) but strips GCLID/FBCLID/MSCLKID (individual-level).

Mitigation: add backup_gclid={gclid} in the Google Ads Final URL Suffix, then use a Query Replacer variable in sGTM to substitute backup_gclid back to gclid before the Conversion Linker processes it. (Conversios, 2025-09-01)

GTM user-provided data field removed (April 2025)

As of April 2025, Google Tag Manager removed the 'user provided data' field from the web GTM container, making the standard GTM web container route for sending hashed email in enhanced conversions no longer available via that mechanism. Server-side GTM or direct API upload is now required. (Stape practitioner note, 2024-08-12 page, updated 2025)

Mixed web + server GA4 setup

Using server-side conversion tracking only for purchase events while leaving other events client-side causes GA4 reporting issues. GA4 should be either fully client-side or fully server-side for consistent reporting; using sGTM as a transport mechanism only (without moving GA4 fully server-side) is not recommended. (Stape, 2024-08-12)

---

EU consent and Smart Bidding dependency

Smart Bidding (Smart Bidding) retrains on Enhanced Conversion data within 2–4 weeks of implementation. If the offline conversion data pipeline breaks — due to cookie policy changes, consent mode misconfiguration, or API deprecation — campaign performance degrades quickly. (groas.com, 2026-06-12)

For EEA-heavy traffic, EU banner interaction rates are the key throttle on EC coverage. Bottom-bar cookie banners achieve 5–20% interaction rate in Germany/Netherlands/Scandinavia, meaning 80–95% of EU visitors never grant ad_user_data. (adnanagic.com via Enhanced Conversions page, 2026-03-12)

The combination of Google Consent Mode v2 Advanced Mode + Enhanced Conversions + server-side tagging can recover 30–50% of conversions lost to cookie rejection in the EEA. (Dataslayer, 2024–2025)

---

Contradictions

---

Related frontier concepts

• Google Ads Conversions API → Smart Bidding (primary downstream beneficiary of EC data)
• Server-Side Tagging (sGTM as the deployment layer; separate page needed)
• Data Manager API (successor architecture; no standalone page)
• Consent Mode Advanced vs Basic Mode (implementation decision that determines EC reach)
• GCLID Storage Patterns (first-party cookie management; no standalone page)
• Conversion Linker (sGTM tag that writes FPGCLAW cookie; no standalone page)
• Safari ITP (browser privacy mechanism that removes GCLIDs; no standalone page)

---

Key terms

Term	Meaning
GCLID	Google Click Identifier — URL parameter appended at ad click; primary key for server-side conversion attribution
GBRAID	iOS app conversion identifier (post-ATT)
WBRAID	iOS web conversion identifier (post-ATT)
Enhanced Conversions	Layer that sends SHA-256 hashed PII alongside GCLID to improve cross-device attribution
FPGCLAW	First-party GCLID cookie written by the Conversion Linker in sGTM
UploadClickConversions	Legacy Google Ads API method for server-side conversion import; new adopters blocked from June 15, 2026
Data Manager API	Unified successor API; GA October 2025; still behind allowlist for some teams as of June 2026
Measurement Protocol	Raw HTTP ingestion layer for GA4 events; in maintenance mode since December 2025
partialFailure	API flag (recommended: true) to prevent one bad record from failing a full batch upload
Match rate	Percentage of EC uploads matched to a Google account; target >80% (fiveninestrategy.com, 2025-12-12)