---
name: set-up-new-customer-tracking
description: >-
  Makes Google Ads distinguish first-time buyers from repeat buyers on the purchase conversion, then
  optionally turns on customer-acquisition bidding for Performance Max so the account can pay a
  premium for genuinely new customers. The buyer-detection logic and tag flag are developer/GTM
  work; VigilDog verifies the new-vs-returning split lands in reports, sanity-checks the ratio against
  backend truth, applies the PMax acquisition setting through campaign updates, and confirms it
  stuck. Use when acquisition cost and retention cost deserve different bids, or a stakeholder wants
  true new-customer CAC. Not the skill for the base purchase tag
  (set-up-google-ads-conversion-tracking), for cart/COGS enrichment
  (set-up-cart-data-and-profit-tracking), or for lead-gen quality dimensions (use
  set-up-custom-variables, the new-customer flag is purchase-specific).
---
# New vs Returning Customer Tracking

## Purpose
Enrich the purchase conversion with a reliable first-purchase flag so reports split new from
returning customers, and, where wanted, configure Performance Max to bid differently for
acquisition. Without this, blended CPA/ROAS hides whether ad spend is buying growth or just
harvesting existing customers.

## When to run
- The business values a new customer differently from a repeat order (almost every ecommerce
  business with meaningful LTV).
- A PMax campaign should prioritize or exclusively target acquisition.
- Stakeholders ask for true acquisition CAC and the account can only show blended CPA.
- Preparing an account for an acquisition-goal campaign structure (prospecting vs retention split).

## When NOT to run
- No purchase conversion yet, set-up-google-ads-conversion-tracking first.
- Lead-gen account: the first-purchase flag is purchase-specific; encode new-vs-existing client as
  a dimension via set-up-custom-variables instead.
- You want margin data on the same event, set-up-cart-data-and-profit-tracking (they coexist but
  are separate implementations).
- Conversion counts are inflated, implement-transaction-id-deduplication first, or the
  new/returning ratio will be wrong too.

## Prerequisites
- Active, deduplicated purchase conversion action.
- A backend or platform capable of answering "is this buyer's first order?" at purchase time
  (order-history lookup by email/customer id is the reliable way; platform-native first-buyer
  fields work; cookies are a weak fallback).
- Developer access to the purchase-page data layer; GTM or gtag access.
- For the bidding phase: a PMax campaign and, ideally, a defined incremental value for a new
  customer.

## Procedure
1. HUMAN STEP (outside VigilDog): the developer adds a boolean new-customer field to the purchase
   data-layer push, computed server-side from order history at purchase time. Cookie-based
   detection only as a last resort, it breaks across devices and cleared cookies, and it detects
   first visit, not first purchase.
2. HUMAN STEP (outside VigilDog): pass the flag to the Google Ads purchase tag, in GTM, enable the
   new-customer data option on the conversion tag and map the data-layer variable; in gtag, add
   the parameter to the conversion event. Publish.
3. HUMAN STEP (outside VigilDog): test both directions, one order with a brand-new email must send
   true, a second order with the same email must send false. Both outcomes must be observed
   before waiting on reports.
4. Verify in reports with VigilDog after 24-48 hours: run `gads_run_gaql_query` segmenting purchase
   conversions by the new-vs-returning dimension. Healthy = both segments present in plausible
   proportion.
   - Only "returning" rows → detection logic always false; back to step 1.
   - Only "new" rows → lookup never matches (commonly guest checkout bypassing the customer
     lookup, or matching on account id instead of email); back to step 1.
5. Ratio sanity check after 7 days: compare the new:returning split from `gads_run_gaql_query`
   against the backend's split for the same period (user supplies the export). Deviations beyond
   a few points usually mean one checkout path (guest/express) skips detection.
6. Decide on acquisition bidding with the user (see decision rules). If enabled:
   - Consult `gads_policy_guardrail` before the first Google Ads write of the session.
   - Apply the customer-acquisition setting on the PMax campaign via `gads_update_campaign`
     (and align goal configuration via `gads_set_campaign_conversion_goal` if needed), preview
     first (validate_only=true default), show the exact mode and any new-customer value, commit
     only after explicit user approval.
7. Confirm the setting stuck: `gads_get_campaign` on the PMax campaign and read back the
   acquisition configuration to the user.
8. Monitor for two weeks via `gads_run_gaql_query`: new-customer share of conversions, blended
   CPA/ROAS, and total volume. Report drift so the user can judge whether the acquisition premium
   is worth it.

## Decision rules
- Detection method: server-side order-history lookup > platform-native first-buyer field >
  cookie. Never accept cookie-only when the platform can do a lookup.
- Match customers by email, not account id, guest checkouts have no account and would all read
  as "new".
- Acquisition mode choice: start with the bid-higher-for-new-customers mode (still serves
  returning customers, pays a premium for new). The new-customers-only mode cuts volume sharply, use it only when a separate retention campaign exists.
- New-customer value: set it to the incremental worth of acquisition (e.g., expected repeat
  margin), not the first-order value, it stacks on top of the conversion value.
- Under target-ROAS bidding, acquisition mode lets Google exceed the ROAS target for new
  customers; judge the campaign on blended ROAS plus new-customer share, not ROAS alone.
- If the acquisition option is not yet offered on the campaign, the platform likely has not seen
  enough flagged conversions, verify data has flowed ~48 h before escalating.
- Ratio validation gate: do not enable acquisition bidding until step 5 passes; bidding on a wrong
  flag actively misallocates spend.

## Common failure modes
- First-visit cookies masquerading as first-purchase detection: inflates "new" massively.
- Guest checkout bypassing the lookup so every guest order reads "new", match on email.
- Only testing the true case, never the false case, and shipping an always-true flag.
- Switching a PMax campaign straight to new-customers-only and losing most volume overnight;
  premium mode first, exclusive mode only with a retention counterpart.
- Reading blended ROAS decline as failure when the campaign is deliberately paying an acquisition
  premium, always report new-customer share alongside.
- Lookback mismatch between the backend's definition of "new" (e.g., first order ever) and the
  platform's window-based view, making the step-5 ratio check fail for definitional rather than
  technical reasons, agree the definition with the user before debugging code.
- Flag implemented on the standard checkout but not on subscription renewals or reorder flows,
  which then all report as new purchases.
- Enabling acquisition bidding on a campaign that also carries all retention traffic, leaving no
  control group to judge the premium against, prefer a structure where retention has its own
  campaign before using the exclusive mode.

## Related skills
- Run before: set-up-google-ads-conversion-tracking, implement-transaction-id-deduplication.
- Run alongside: set-up-cart-data-and-profit-tracking (same purchase event, different enrichment).
- Run after: build-customer-match-lists (feed retention/exclusion lists),
  launch-pmax-full-assets-ecommerce-campaign, run-a-monthly-performance-review (track acquisition
  share).
- Strategic follow-up: run-a-quarterly-business-review is where the acquisition-vs-retention
  budget split gets decided once a quarter of segmented data exists.