Tracking & measurement

This page is the operational source of truth. The numbers the media planner uses as benchmarks — front-end ROAS, blended CPA, retention rates — must reconcile back to the events and windows described here. If you change a value on this page, the planner should be re-baselined before it goes to a buyer.

Conversion events, by step

Each funnel step fires a single conversion event. Two categories:

• Optimization events feed the platform's bidding (Meta's "Purchase" optimization, Google's "Conversion" action). High-intent, value-bearing events only.
• Reporting events exist for internal measurement. They never go into a campaign's optimization goal — putting them there trains the algorithm on the wrong signal.

UTM parameter template

The template stored in registry/campaigns.json per campaign:

utm_source={source}&utm_medium={medium}&utm_campaign={campaign}&utm_content={adset}&utm_term={creative}

Click ID persistence across the OTO chain

The OTO pages are separate URLs (the buyer is taken off the processor's hosted page onto our own upsell page, then back to the processor). State must survive the round trip. The mechanism:

1. Land on core checkout URL with the platform's click ID appended as a query string (fbclid, gclid, yclid, msclkid, epik, etc. — the field is per-platform, stored in tracking.click_id_param).
2. After successful payment the processor redirects to ty_core and includes the click ID in the redirect URL. Verify this is wired in production — most processors strip query strings by default.
3. From ty_core, fire PurchaseConfirmed with fbclid (or whichever) attached as both an event parameter and a first-party cookie. The cookie is read by OTO1 / OTO2 pages served via separate URLs.
4. Each OTO page reads document.cookie and merges the click ID into both the upsell link (so it survives the next redirect) and the pixel fire. The OTO conversion events must include the click ID as an event parameter — this is the single most-broken integration we see; audit every campaign's OTO pages in the launch checklist.
5. On ty_case (the call-booking thank-you), write the click ID to the CRM record as external_id. This makes attribution + re-engagement campaigns work later.

Attribution window vs. platform default

The platform defaults (Meta 7-day click, 1-day view; Google Ads default 30-day click; etc.) optimize for volume. We hold tighter windows for reporting, stored in tracking.attribution_window_days per campaign:

• The default is 7 days for low-ticket offers with short consideration cycles (the OTO2 → call funnel needs urgency).
• Stretch to 14 or 30 days only when running a higher-considered / higher-ticket offer where the buyer needs time between ad-click and purchase.
• The window is enforced in the warehouse SQL, not on the platform — we still let the platform optimize on its default and just re-attribute for our own CPA math.

Confirmed vs. pending sale, refunds, chargebacks

The pixel fires on the first signal from the processor (Purchase). Three days later the order may have been refunded. The four states the planner assumes:

1. Pending — processor says paid but our warehouse hasn't received the webhook yet (typically < 60s, occasionally hours). Treat as revenue for the platform's optimization; treat as zero for our own CPA math until confirmed.
2. Confirmed — webhook received, order line item visible in the warehouse. This is what the media planner assumes.
3. Refunded — buyer refunded within the window. Subtract from gross in the day's net. Net contribution and ROAS numbers drop. Auto-decrement the refund_rate in the media planner back to reality.
4. Chargeback — bank reversal. Different from refund: fees apply, the platform usually bills us, and the customer is barred from the upsell pages. Treat as a 100% refund + a configurable chargeback-fee % in the planner.

Both refund and chargeback events must reconcile backward against the original conversion event — when the planner reports a day's net contribution, that number is the difference of the day's confirmed events minus refunds, not the day's pixel-fires. The verifier doesn't catch refund lag; that's a nightly warehouse job.

The planner's numbers are downstream of this page

The default values for refund_rate, fee_rate, and the conversion rates in the campaign presets (Conservative / Base / Aggressive) are calibrated against the events and windows described above. If you change:

• which event fires at a step (e.g. swap Purchase for a custom OTO2Lead)
• the attribution window for a campaign
• how value is set on the optimization events

…then the planner's numbers will drift from reality. Update registry/campaigns.json's presets.* and the matching field defaults in /plan/ on the same day, and notify the campaign owner in the campaign notes.