Google Ads Integration

Google Ads

Configure conversion forwarding to Google Ads using gads/google_ads provider aliases.

Audience: Performance marketing teams optimizing paid search and shopping conversions.

Critical: Preferred provider key is gads; google_ads alias is also supported for compatibility.

Integrations Overview Event Mapping Operations

Who This Page Is For

Use this page when you need to forward conversion events to Google Ads and maintain a stable mapping/filter contract.

Quick Start (2-5 Minutes)

Configure provider

Set conversion ID/label and optional value-based option.

PUT /api/v1/sites/:siteId/integrations/gads

Map high-value events

Map purchase and add_to_cart equivalents for campaign optimization.

{ "eventMapping": { "purchase": "purchase", "add_to_cart": "add_to_cart" } }

Apply optional filters

Forward only qualifying events based on payload conditions.

{ "eventFilters": { "purchase": { "enabled": true, "conditions": [{ "field": "order.total", "operator": "gte", "value": 1 }] } } }

Test integration

Run connectivity test on provider route.

POST /api/v1/sites/:siteId/integrations/gads/test

Inspect logs

Diagnose failed sends and payload issues.

GET /api/v1/sites/:siteId/integrations/gads/logs?limit=50

Google Ads config example

{
"enabled": true,
"config": {
  "conversionId": "AW-123456789",
  "conversionLabel": "purchase_label",
  "valueBased": true
},
"eventMapping": {
  "purchase": "purchase"
},
"testMode": false
}

Required Fields / Minimum Payload

Field	Required	Type	Used by events	Description
`provider`	Required	`gads or google_ads`	Provider route	Integration provider selector.
`config.conversionId`	Required	`string`	Google Ads update payload	Google Ads conversion ID.
`config.conversionLabel`	Required	`string`	Google Ads update payload	Conversion label for target action.
`config.valueBased`	Optional	`boolean`	Google Ads update payload	Use event/order value in conversion sends.
`eventMapping`	Optional	`Record<string,string>`	Google Ads update payload	Canonical event mapping table.

Currency Behavior

Google Ads conversion currency is resolved with fallback order: event -> order -> site -> EUR.
Provider forwarding does not force USD.
If value-based conversions are enabled, ensure currency and value come from the same source payload.

Event or Endpoint Decision Matrix

Scenario	Use This	Why
Preferred production setup	PUT /integrations/gads	Canonical provider key for clarity.
Compatibility with legacy tooling	PUT /integrations/google_ads	Alias supported for backward compatibility.
Validate credentials and send pipeline	POST /integrations/gads/test	Prevents silent launch failures.
Review failure diagnostics	GET /integrations/gads/logs	Operational visibility into send outcomes.
Need provider defaults	GET /integrations/gads/mappings	Reference starting mapping set.

Common Errors and Fixes

Test endpoint fails for Google Ads

Cause: Invalid conversion ID/label pair.

Fix: Verify values in Google Ads account and re-test.

No value passed for conversions

Cause: valueBased disabled or purchase payload missing totals.

Fix: Enable valueBased and ensure purchase/order totals are present.

Events filtered unexpectedly

Cause: eventFilters conditions too restrictive.

Fix: Audit conditions and compare with actual payload shape.

Events in logs but absent downstream

Cause: testMode enabled or downstream account policy issue.

Fix: Disable testMode and verify provider account constraints.

Production Checklist

Canonical provider key (gads) is used in production automation.Required
conversionId and conversionLabel are validated with test endpoint.Required
purchase mapping is explicitly configured.Required
valueBased behavior is aligned with campaign measurement strategy.Required
Delivery logs are reviewed after each major release.Required