4 Star × DataStudios · Artifact

Implementation Plan

Objective 1 — Data Manager API, phased

Data Manager API — Offline Conversions Implementation Plan

Objective 1 from the client doc "4 Star Data Setup": get the Data Manager API set up for offline conversions in Google Ads + events in GA4, with per-row visibility into which rows did not import, orchestrated in n8n. (= Phase 1 / sold scope.)

Author: Diego Sanz (Vantage Node). Drafted 2026-06-18, informed by the platform audit (platform-audit-2026-06-18.md) and client ground truth (4star-data-setup-notes.md). Source of truth = Supabase (CRM SQL Server, hourly sync).

0. The decision everything hinges on — the match key

An offline Quote/Order only counts in Google Ads if it can be tied back to the original ad click. Three possible keys; we must confirm which exist in Supabase before any build:

gclid / gbraid / wbraid — captured at RFQ submission and persisted onto the row. The container already runs a Conversion Linker (_gcl prefix), so gclid is captured in the cookie; unknown whether it's written to the form payload → CRM → Supabase.
Enhanced Conversions for Leads (hashed email/phone) — no gclid needed; Google matches on hashed PII. The dataLayer carries user_email + user_phone, so viable if they land in Supabase. (Depends on the RFQs enhanced-conversions setup, currently flagged.)
Both (gclid primary, ECL fallback) — most robust.

Risk: if none of these is stored per row, a website tracking change is required first (capture + persist gclid/PII at RFQ submit). That is the difference between "straightforward" and "blocked on a code change." This is the #1 discovery item — see mezar-discovery-questions.md.

1. Target conversion actions (already exist — confirmed in audit)

CRM stage	Google Ads conversion action	Current state
RFQ	`RFQs` (web tag) + `rfq_thankyoupage_ga` (GA4 import, observation)	Active; EC ⚠ setup issue
Quote	`Quotes` — "Website (Import from clicks)"	Active — offline import target
Order	`Orders` — "Website (Import from clicks)"	⚠ Needs attention — offline import target

The offline-import actions for the two CRM stages already exist; we feed them, we don't create them. Confirm each action's count setting, value handling, and conversion window, and diagnose the Orders "needs attention" state before go-live.

2. Phased plan

Phase 0 — Foundations (actionable NOW, no new access)

[ ] Mint dsanz@ user OAuth token (Google Cloud OAuth client; save secret to host C:\DataStudiosGithub\credentials\). Data Manager API needs no developer token. Scopes: Google Ads + GA4 (Analytics).
[ ] Run read smoke-tests (Ads list-accessible-customers, GA4 Admin get-property) as the real "API write path is viable" signal.
[ ] In Ads, open Quotes + Orders: confirm import-readiness, value, window, count; diagnose Orders "needs attention."
[ ] Triage the RFQs enhanced-conversions setup issue (matters if matching on PII).
[ ] Decide GA4 ingestion mechanism: Measurement Protocol (per-stream API secret, mature) vs Data Manager events. Lock one.

Phase 1 — Data model / discovery (needs Supabase access)

[ ] Map Supabase schema for RFQ / Quote / Order: stage, value, currency, timestamps, and the match-key columns (gclid, hashed/plain email, phone, company, name).
[ ] Confirm the join: how a Quote/Order row references its originating RFQ (and its match key).
[ ] Define the incremental query: "rows whose stage advanced to Quote/Order since last run," with a watermark (updated_at / sync timestamp).
[ ] Pull sample rows to validate payload shape end-to-end.

Phase 2 — Pipeline build (needs n8n access)

[ ] Stand up the n8n workflow (see §3).
[ ] Implement the per-row failure write-back (see §4) — explicit client requirement.
[ ] Dry-run against Ads/GA4 with a small batch; verify conversions land.

Phase 3 — GA4 events

[ ] Send the same offline events to GA4 via the chosen mechanism (parity / observation), keyed to event time, deduped by quote_id/order_id.

Phase 4 — Validation & reconciliation handoff

[ ] Confirm conversions appear in Ads + GA4; check diagnostics.
[ ] Hand the per-row import log into the reconciliation workstream (Objective 2).

3. n8n workflow shape

Schedule (daily) → Query Supabase (new/changed Quote+Order rows since watermark) → Transform → Data Manager payload (match key + conversion action + conversion time + value) → Upload to Google Ads (Data Manager) → Parse per-row response → Write status back to Supabase (success/fail + error per row) → Alert on failures → Advance watermark. (GA4 events as a parallel branch in Phase 3.)

Founder principles to bake in (from the client doc): - Daily cadence is fine — Supabase sync is hourly; do not promise sub-hour freshness. - Exclude unsettled days — set the upload cutoff to skip the still-moving recent window. - Conversion time = actual event time, not upload time (correct attribution dating). - Idempotency — use quote_id/order_id as the dedupe key so re-runs never double-count (relevant given the RFQ-side over-counting already observed).

4. Failure tracking ("which rows did not get imported") — first-class, not optional

Capture the Data Manager API's per-row / partial-failure response on every run.
Write back to Supabase a status per row: import_status (pending/success/failed), import_error, imported_at, conversion_action, run_id. (Or a dedicated conversion_import_log table keyed by quote_id/order_id.)
Surface failures: a daily alert (email/Slack via n8n) listing failed rows + reasons, and a simple view/artifact of import status over time. This log is also a direct input to the reconciliation workstream.

5. Decisions to lock before building

#	Decision	Options	Owner
1	Match key	gclid / ECL (hashed PII) / both	Client + Diego (needs Supabase)
2	GA4 ingestion	Measurement Protocol / Data Manager	Diego
3	Cadence + unsettled-day cutoff	daily; cutoff = ? days	Diego + client
4	Where per-row status lives	Supabase column / log table / sheet	Diego
5	Value per stage	use Quote/Order $ value or fixed?	Client

6. Dependency / blocker status

Dependency	Status	Needed for
Google Ads / GA4 / GTM access	✅ active	discovery, validation
dsanz@ OAuth token	⏳ to mint (Phase 0)	all API writes
Supabase access + schema	❌ blocked	Phases 1–2 (and match-key confirmation)
n8n instance	❌ blocked	Phase 2
Match key in Supabase	❓ unknown	whether a website change is needed first

Net: Phase 0 de-risks now; the pipeline is gated on Supabase + n8n. Chase the match-key confirmation hardest — see the discovery questions for Mezar.