Pass Google Ads Offline Conversions via API for ROAS
A buyer clicks a Search ad, submits a lead form, and triggers a standard client-side conversion event. Google Ads registers a conversion and assigns a $95 Cost Per Acquisition (CPA) to that click. Inside your CRM, that specific lead turns out to be a junk submission from a competitor testing your form. Three hours later, a different user clicks an ad, submits the same form, and closes a $35,000 contract two weeks down the line. To Google’s Smart Bidding algorithm, both clicks generated the exact same output: one lead event.
When media buyers rely exclusively on browser-based pixel events to feed Google’s machine learning models, Target CPA (tCPA) and Target ROAS (tROAS) optimize for volume rather than revenue. The algorithm doubles down on ad groups, search terms, and audiences that deliver high volumes of low-intent form fills. Passing offline conversions via the Google Ads API fixes this optimization mismatch by feeding validated downstream revenue events back into the ad account.
Why browser-only conversion tracking damages Value-Based Bidding
Client-side tracking scripts are increasingly inaccurate. Browser privacy controls, ad blockers, and mobile operating system restrictions strip tracking parameters long before a user completes a high-value action in your sales funnel.
Safari Intelligent Tracking Prevention (ITP) caps client-side JavaScript cookie lifetimes to 7 days or 24 hours depending on query parameter detection. When your sales cycle spans 30, 60, or 90 days between lead submission and deal close, client-side attribution collapses. The browser context that generated the original click parameter is long gone by the time real money changes hands.
Google Ads relies on specific identifiers to map a conversion back to an ad impression and click:
- GCLID (Google Click Identifier): A unique query string parameter appended to landing page URLs for web traffic originating from Google Ads clicks.
- GBRAID: Parameter used for iOS app-to-web or web-to-web conversions where individual user tracking is restricted under Apple’s App Tracking Transparency (ATT) framework. Optimized for aggregated measurement.
- WBRAID: Parameter appended to URLs for web conversions on iOS devices when direct tracking identifiers cannot be read.
- Enhanced Conversions for Leads (User Data): SHA-256 hashed first-party data (email address, phone number, physical address) passed when a click identifier is missing or stripped by browser settings.
Relying on server-side event transmission bypasses frontend script suppression entirely. By establishing a direct pipeline between your internal database or CRM and Google’s servers, you protect conversion data against browser drop-off. For a deeper breakdown on stabilizing server-side architecture, see our guide on how to Fix Missing Conversion Postbacks: S2S Tracking Guide.
How does the Google Ads API conversion pipeline operate?
Offline Conversion Import (OCI) via the Google Ads API pushes conversion events directly to Google’s ConversionUploadService. Instead of relying on a user loading a page containing a global site tag, your backend application constructs an HTTP POST payload containing the click identifier, timestamp, conversion action ID, and precise conversion value.
| Integration Method | Data Latency | Scalability | Attribution Accuracy | Engineering Overhead |
|---|---|---|---|---|
| Manual CSV Upload | 24 to 72 hours | Low (manual uploads, file formatting errors) | Moderate (subject to human lag) | Zero dev work |
| Third-Party Middleware (Zapier/Make) | 15 to 60 minutes | Medium (rate-limited by task limits and cost) | High | Low (no-code webhook setups) |
| Google Ads REST/gRPC API | Near Real-Time (Batching recommended) | High (Handles millions of events daily) | Highest (Deterministic server-side matching) | Moderate (OAuth + backend engineering required) |
Manual CSV uploads fail as spend scales. A missing timezone offset or malformed string breaks the upload, delaying data ingestion by days. Smart Bidding relies on consistent data velocity; delays in data ingestion distort bidding models, causing under-bidding on high-value terms during active auction adjustments.
Step-by-step guide to passing offline conversions via the Google Ads API
Step 1: Capture and store click parameters at lead entry
Modify every public lead form on your web properties to parse URL query parameters. Extract gclid, gbraid, and wbraid from the landing page URL and store them alongside the lead record in your database.
If a user lands on https://example.com/landing-page?gclid=Cj0KCQiA..., store that string in a hidden form field or local storage session. When the submission executes, write the click parameter to your customer record alongside first-party details like normalized email and phone number.
Step 2: Obtain Google Ads API credentials and developer access
To send server-side requests to Google Ads, set up an API project within the Google Cloud Console:
- Create a project in Google Cloud Console and enable the Google Ads API.
- Generate an OAuth 2.0 Client ID and Client Secret.
- Authenticate through your Google Ads Manager Account (MCC) to generate a long-lived Refresh Token.
- Apply for an API Developer Token inside your Google Ads MCC under Tools & Settings > API Center. (Test accounts function immediately under Basic Access).
Step 3: Map backend CRM milestone events to conversion actions
Define clear conversion boundaries inside Google Ads under Goals > Conversions > Summary. Create conversion actions with the source set to Import / Other data sources or CRMs.
Do not pass raw lead counts as offline conversion values. Map specific financial milestones:
Stage_1_Qualified_Lead= $50 baseline valueStage_2_Demo_Completed= $250 calculated valueStage_3_Closed_Won= Actual invoice transaction amount (e.g., $12,450.00)
To determine precise economic values per stage, review our framework on Max Allowable CPA: How to Bid Based on LTV before deploying automated bidding rules.
Step 4: Format and execute the REST API upload request
When an offline conversion event fires in your backend (e.g., an invoice status changes to PAID), construct a POST payload to the uploadClickConversions endpoint.
Endpoint URL target (using API v17):
POST https://googleads.googleapis.com/v17/customers/{CUSTOMER_ID}:uploadClickConversions
Required Headers:
Authorization: Bearer {ACCESS_TOKEN}developer-token: {DEVELOPER_TOKEN}login-customer-id: {MCC_CUSTOMER_ID} (If managing child accounts via MCC)Content-Type: application/json
JSON Request Body Payload Structure:
{
"conversions": [
{
"conversionAction": "customers/1234567890/conversionActions/987654321",
"conversionDateTime": "2026-03-29 14:22:05-05:00",
"conversionValue": 4500.00,
"currencyCode": "USD",
"gclid": "Cj0KCQiA-xuyBhC-ARIsAhbj473X9...",
"customVariables": [
{
"customVariable": "customers/1234567890/customVariables/112233",
"value": "Enterprise_Plan"
}
]
}
],
"partialFailure": true
}
Always set partialFailure: true. This ensures that if one item in a batch of 50 conversions contains an expired GCLID, the remaining 49 valid conversions process successfully rather than rejecting the entire network call.
Step 5: Implement Enhanced Conversions for Leads fallback
When GCLID parameters are stripped by external privacy tools or cross-device journeys, populate the userIdentifiers array inside the JSON request body. Normalize and hash customer strings with SHA-256 before upload.
Formatting rules for hashing:
- Email: Strip leading and trailing whitespace, convert all characters to lowercase, then compute SHA-256 (e.g.,
john.doe@example.com). - Phone Number: Remove all non-digit characters, format in E.164 standard (e.g.,
+14155552671), then compute SHA-256.
{
"conversions": [
{
"conversionAction": "customers/1234567890/conversionActions/987654321",
"conversionDateTime": "2026-03-29 14:22:05-05:00",
"conversionValue": 1200.00,
"currencyCode": "USD",
"userIdentifiers": [
{
"hashedEmail": "230528c4b922418413e15553e1a6c429c313... (SHA-256 hash)"
},
{
"hashedPhoneNumber": "a4d334e12c1b489a2e6f432..."
}
]
}
],
"partialFailure": true
}
Handling API response codes and synchronization errors
Parsing API response objects prevents silent tracking breaks. Below are common API error strings returned by the ConversionUploadService inside the partialFailureError object and how to resolve them:
TOO_RECENT_CLICK
Google requires 4 to 6 hours between the ad click and the offline conversion processing call to index the click parameter across its infrastructure. If your system pushes an offline event 10 minutes after form submit, the API returns this error. Fix: Implement a queueing delay in your backend code; hold event processing for 6 hours after initial click capture before executing the API POST request.
EXPIRED_CLICK
The click identifier passed is older than Google Ads' allowed conversion window (typically 90 days maximum). Fix: Filter out backend records where the original capture timestamp exceeds 85 days prior to payload construction.
CONVERSION_ALREADY_EXISTS
A conversion with the exact same click identifier, conversion action ID, and timestamp has already been recorded. Fix: Ensure idempotent event IDs exist on your transaction server to prevent retry loops from firing duplicate payloads.
Transitioning Smart Bidding to Value-Based Bidding (VBB)
Once your offline conversion pipeline uploads data reliably for 30 consecutive days, transition campaign bidding strategies from volume acquisition to value scaling.
Do not switch directly from Target CPA to a high Target ROAS overnight. Abrupt bidding changes cause machine learning recalibration resets, freezing auction participation.
- Verify Offline Volume: Ensure the imported offline conversion action has recorded at least 30 to 50 conversion events in the past 30 days within the Google Ads account.
- Adjust Primary Conversion Goals: Switch the offline conversion action setting from Secondary action (observe only) to Primary action (used for optimization). Downgrade client-side web form submissions to Secondary status.
- Set Target ROAS Baseline: Calculate your baseline ROAS over the previous 30-day window:
Baseline ROAS = (Total Recorded Offline Conversion Value / Total Google Ads Spend) * 100 - Apply Target ROAS: Set your campaign target ROAS equal to or slightly below your historical baseline ROAS for the first 14 days. If historical backend ROAS is 250%, set the campaign target at 230% to give the bidding algorithm flexibility to collect baseline data without throttled delivery.
- Account for Conversion Lag: B2B funnels often experience long lag windows between click and close. If your customer journey requires 21 days from click to revenue upload, evaluate performance using 30-day window snapshots rather than 7-day reports.
To evaluate how backend revenue data changes your holistic funnel economics across multiple traffic networks, read our breakdown on How to Calculate Blended eCPA Across Multi-Channel Funnels.
Your 7-day deployment checklist
Follow this checklist to build and deploy your Google Ads API offline conversion engine:
- Day 1: Audit forms across all landing pages. Update hidden input fields and session storage scripts to capture
gclid,gbraid, andwbraid. - Day 2: Configure OAuth 2.0 credentials in Google Cloud Console and submit your Developer Token request inside your Google Ads Manager Account.
- Day 3: Create new offline conversion actions inside Google Ads. Select Import from CRM/Server and set primary/secondary statuses to Secondary for testing.
- Day 4: Write the backend conversion script. Implement SHA-256 data normalization functions for email and phone numbers, and set up a 6-hour delay queue to avoid
TOO_RECENT_CLICKerrors. - Day 5: Send test payloads using real GCLIDs generated from live search queries (or test conversions). Enable
partialFailure: trueand inspect payload response bodies for zero errors. - Day 6: Verify that uploaded conversions appear inside the Google Ads UI under Goals > Conversions with correct values and transaction counts.
- Day 7: Switch offline conversions to Primary optimization actions, adjust client-side leads to Secondary, and begin a 14-day transition toward Target ROAS bidding.
Frequently Asked Questions
What happens if a GCLID is stripped or unavailable?
If the GCLID parameter is missing due to cross-device navigation or strict browser privacy settings, populate the userIdentifiers payload object with normalized SHA-256 hashed emails and phone numbers. Google's Enhanced Conversions for Leads system matches these hashed attributes against signed-in Google accounts to assign attribution.
How long can I wait between an ad click and sending an offline conversion?
The maximum upload window for click-based conversions is 90 days from the original ad click timestamp. Any payload sent with a click identifier older than 90 days returns an EXPIRED_CLICK error. For optimal Value-Based Bidding performance, push conversions continuously as events happen inside your backend CRM.
Can I pass negative values or adjustments via the Google Ads API?
Yes. You can upload conversion adjustments using the UploadConversionAdjustments request method. This service allows you to retract a previously uploaded conversion entirely or restate its value downward if a customer cancels, requests a refund, or defaults on a contract payment within your attribution window.