Connect a Google ad click to a verified Shopify app customer event.

This is for Shopify app businesses that run Google Ads to an app-owned landing or installation page and can preserve Marlo's acquisition ID in a signed first-party session through the Shopify authentication flow.

1. 01A Marlo deployment with Google OAuth configured
2. 02Owner or admin access in Marlo
3. 03A Google user authorised for the conversion customer or its manager account
4. 04A Google Ads conversion action intended for imported click conversions
5. 05A Marlo tracking source on an app-owned HTTPS origin
6. 06Consent and privacy disclosures appropriate to the traffic and jurisdiction
7. 07A server-side event after Shopify or billing verification

1. 01Confirm the Google Ads customer that owns the conversion action
2. 02Create or select a conversion action for imported click conversions
3. 03Record the 10-digit conversion customer ID
4. 04If access runs through a manager account, also record that login customer ID
5. 05Do not use a conversion action resource name; Marlo needs its numeric ID

Google's current field mapping distinguishes the conversion account from an optional manager login account.

1. 01Open Google Ads in Marlo
2. 02Choose Connect Google Ads
3. 03Grant the Google Ads and Data Manager scopes
4. 04Enter the conversion customer ID
5. 05Choose or enter a manager login customer only when the conversion account is reached through that manager
6. 06Select account
7. 07When account discovery is configured, refresh conversion actions and choose the expected action

Changing either selected account disables existing mappings so an old conversion action cannot silently resume against a new account. Marlo encrypts the refresh token. It does not receive a Google password, create campaigns or change bids, budgets, targeting or ads.

Install the hosted script on the app's own frontend or marketing/install page—not in merchant storefront themes.

<script async src="https://withmarlo.app/v1/marlo.js" data-key="marlo_pk_REPLACE_WITH_YOUR_PUBLIC_KEY"></script>

1. 01Open a test URL containing a real test gclid, gbraid or wbraid issued for traffic you are entitled to measure
2. 02Open Tracking in Marlo and confirm the page_view
3. 03Preserve window.marlo.getAcquisitionId() in your signed server session before leaving the app-owned flow
4. 04Never replace Shopify OAuth state or nonce with the acquisition ID

1. 01Keep Validation only enabled
2. 02Choose the tracking source
3. 03Choose install, trial started, trial converted, qualified or paid
4. 04Select the Google conversion action or enter its numeric ID and name
5. 05Optionally set a fixed value and three-letter currency; otherwise Marlo uses a valid server event value
6. 06Confirm your consent and processing policy
7. 07Create the mapping

A qualified event is a rule your own server evaluates; Marlo does not invent a qualification score. Marlo sends Google Ads offline conversions with eventSource=IN_STORE, as Google's Data Manager contract requires. This API enum does not mean the Shopify merchant made a physical in-store purchase; the server-verified app lifecycle event remains the evidence.

Use the same acquisition ID and a stable unique event ID. A retry with the same event ID is deduplicated. The customer reference stays in Marlo and is not included in the Google payload.

curl --request POST 'https://app.withmarlo.app/api/tracking/server-events' \
  --header 'Authorization: Bearer marlo_sk_REPLACE_WITH_YOUR_PRIVATE_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"teamSlug":"acme","publicKey":"marlo_pk_REPLACE_WITH_YOUR_PUBLIC_KEY","eventId":"payment_01J123456789","acquisitionId":"01J123456789ABCDEFGHJKMNPQ","name":"paid","customerRef":"example-shop.myshopify.com","amountCents":4900,"currency":"USD","occurredAt":"2026-07-22T12:00:00Z"}'

See the server-event guide for install, trial, qualified and payment examples.

1. 01Confirm the event appears in Tracking with a Server evidence badge
2. 02Open Google Ads and find the new queue row
3. 03Confirm click evidence is gclid, gbraid or wbraid rather than none
4. 04Expect validated in validation-only mode; unattributed means Marlo found no supported click ID
5. 05Fix any payload error and use Retry only when the row still retains click evidence
6. 06Turn Validation only off only after the selected account, action, value and consent path are correct
7. 07Send a new test lifecycle event; the mode change does not replay old validated rows
8. 08Allow at least 30 minutes before expecting asynchronous diagnostics
9. 09Confirm the conversion in Google Ads after Google finishes processing

1. 01queued: waiting for the first Data Manager request
2. 02validated: Google accepted validation-only syntax without applying a conversion
3. 03accepted: ingestion was accepted and diagnostics may still be processing
4. 04retrying: a network, quota or server failure will retry with backoff
5. 05rejected: Google returned a permanent or asynchronous processing error
6. 06unattributed: no supported click ID was captured for that acquisition
7. 07Invalid click ID: repeat with genuine eligible test traffic; never fabricate a click ID
8. 08No consent: review advertiser defaults, event consent and your legal basis
9. 09Duplicate transaction: keep one stable event ID and conversion-action mapping
10. 10Wrong account: check conversion customer, optional manager login and numeric action ID

Google's diagnostics guidance says request processing is asynchronous. Marlo polls with bounded backoff and shows Google's reason codes.

1. 01Collect advertising click IDs only where your policy and consent path permit it
2. 02Do not upload personal data or customer information you are not entitled to process
3. 03Marlo sends the click ID, event time, action, transaction ID and optional value/currency—not the merchant domain or email
4. 04Raw tracking events are deleted and upload click, acquisition and merchant identifiers are scrubbed after 180 days
5. 05Source event IDs are hashed before storage in the Google upload queue
6. 06The browser public key grants no reporting access
7. 07The private marlo_sk_ key stays server-side
8. 08Connection, mapping, validation-mode and disconnection changes are audited
9. 09Google may reject old events or identifiers outside its supported window

1. 01Open Google Ads in Marlo
2. 02Choose Disconnect
3. 03Confirm token revocation
4. 04If Google cannot confirm revocation, fix the provider/network error and retry; Marlo does not claim success or erase its retry credential first
5. 05Verify the screen returns to the disconnected state
6. 06Reconnect and create fresh mappings if you later use a different account
7. 07Rotate the Marlo browser or server key separately if either key was exposed

After Google confirms revocation, Marlo removes its stored refresh token and disables active mappings. Historical mapping and diagnostic rows remain for auditability, but no new conversion is uploaded until a new connection and mapping exist.

1. 01Attribution is possible only when an eligible Google click ID is captured and the same acquisition ID reaches the verified server event
2. 02Shopify App Store and cross-domain journeys do not reliably preserve arbitrary query parameters
3. 03Google reporting can take hours to settle after ingestion
4. 04Marlo does not create conversion actions
5. 05Marlo does not upload past events when a new mapping is created
6. 06Marlo does not create or optimise campaigns, bids, budgets, targeting or creative
7. 07OAuth availability depends on Marlo deployment configuration and Google verification