Conversion Tracking & Attribution (Pixels, UTM, Analytics)

Free — GPL coresize Lplanned, not built

Generated from docs/plan/core/conversion-tracking-attribution/PLAN.md in the AstroBaaS repository. Nothing described below is implemented — it is the written plan for it.

A free core feature that fires tracking pixels at checkout and provides basic UTM parameter tracking. Paid tiers add cross-channel attribution, customer journey mapping, and advanced analytics.

The problem

Merchants can’t track which ads, emails, or social posts actually drove sales. Attribution is broken: they see orders but don’t know if order came from Google Ads, Instagram, or a referral. They manually tag orders with ad platform IDs and lose data.

What it does

• Conversion pixel firing at checkout (Facebook Pixel, Google Analytics 4, custom pixel URLs)
• UTM parameter tracking (utm_source, utm_medium, utm_campaign, utm_content, utm_term)
• First-click and last-click attribution (order assigned to first marketing touch or most recent touch)
• Pixel parameter pass-through (pass customer email, order ID to pixel for conversion validation)
• Session storage of attribution source (store referrer, UTM parameters, ad ID in session; retrieve at checkout)
• Checkout page pixel firing (show merchant which pixels are loaded and firing at checkout)
• Order analytics by attribution source (how many orders from Google Ads, Facebook, organic, referral, email, etc.)
• Revenue by attribution source (total revenue from Google Ads, etc.)
• Customer journey visualization (show path: Facebook Ads → organic search → email → checkout)
• UTM parameter parsing and validation (warn merchant if UTM values are malformed)

What it deliberately does NOT do

Each boundary carries its reason. A boundary without a reason gets crossed by the next person who reads this.

• Multi-touch attribution (order gets credit split across all touches) — paid ‘multi-touch-attribution’ owns ML and statistical modeling
• Cross-device tracking (customer clicks ad on mobile, purchases on desktop) — requires device fingerprinting or login tracking; paid owns this
• Attributed customer LTV (track lifetime value of customers acquired from each channel) — requires cohort analysis; paid owns this
• Ad platform integrations (auto-import cost data from Google Ads, Facebook Ads Manager) — paid ‘advertising-integrations’ owns credential sync
• ROAS calculation (revenue / ad spend by channel) — requires ad cost data; paid owns this if ad spend is auto-imported
• Attribution API (send conversion data back to Google Ads, Facebook for retargeting) — paid ‘conversion-api’ owns this

Data model

New entities: tracking.pixels {id, merchantId, pixelType (facebook/google-analytics-4/custom), pixelId (url or id), isActive, firedAtCheckout (bool), createdAt}; tracking.sessions {id, sessionId, visitorId (hashed), referrer, utmSource, utmMedium, utmCampaign, utmContent, utmTerm, customParams (json), adId, firstTouchAt, lastTouchAt}; tracking.attributions {id, orderId, visitorId (hashed), firstTouchSource, firstTouchMedium, firstTouchCampaign, lastTouchSource, lastTouchMedium, lastTouchCampaign, attributionModel (first/last), createdAt}; tracking.pixelsFired {id, sessionId, pixelType, pixelId, firedAt, conversionData (json)}; tracking.analytics {id, date, source, medium, campaign, ordersCount, revenue, conversionRate}.

API

• POST /api/tracking/pixels
• GET /api/tracking/pixels
• DELETE /api/tracking/pixels/{id}
• GET /api/tracking/pixels/test
• POST /api/tracking/sessions
• PATCH /api/tracking/sessions/{id}
• GET /api/tracking/checkout-pixels
• POST /api/tracking/conversions
• GET /api/tracking/analytics
• GET /api/tracking/analytics/by-source
• GET /api/tracking/analytics/by-campaign
• GET /api/tracking/customer-journey/{orderId}
• GET /api/tracking/attribution/{orderId}

Every route added here must also appear in src/pages/openapi.json.ts — a test fails the build if it does not.

Admin

Pixel management: register Facebook Pixel, Google Analytics 4, custom pixels; show status. Pixel testing: test each pixel to verify it fires at checkout; show payload sent. Checkout pixel code: show JavaScript snippet merchant must embed in checkout page. Attribution analytics: view orders by source/medium/campaign; show count and revenue. Customer journey dashboard: for each order, show path (referrer → pages visited → checkout). Attribution model selector: choose first-click or last-click (core) or others (paid). UTM parameter validation: warn if utm_source is empty or utm_medium has typo. Custom parameter setup: merchant can define custom parameters (e.g., ‘promo_code’, ‘season’) and track them.

The seam — why this is core

Core owns free pixel firing (Facebook, Google Analytics 4, custom pixel URLs) and basic UTM tracking. Paid modules own multi-touch attribution (order gets credit split — statistical models), cross-device tracking (link mobile and desktop behavior — device fingerprinting), customer LTV by channel (lifetime value of customers from each source — cohort analysis), ad platform integrations (auto-import cost data from Google Ads — credential sync and ROAS), attribution API (send conversion data back to ad platforms — retargeting).

Core can fire pixels at checkout; paid modules own cross-channel attribution ML, UTM parameter tracking, and unified customer journey

Dependencies

• Orders module (to store attribution data on orders, calculate revenue by source)
• Customers module (optional, to link conversions to customer records for LTV)
• Settings (to store pixel IDs, pixel types)

Acceptance checks

Each of these must be able to fail. Before claiming this is done, break the code deliberately and watch each one go red.

• A visitor lands on store via Google Ads; session captures utm_source=‘google’, utm_medium=‘cpc’, utm_campaign=‘summer-sale’
• Visitor navigates to checkout and places order; order record stores attribution: firstTouchSource=‘google’, lastTouchSource=‘google’
• Facebook Pixel is registered in admin and test-fire sends pixel request to Facebook with merchant pixel ID and custom data
• UTM parameter validation warns merchant if utm_source is empty or utm_medium is not in standard list
• Analytics dashboard shows breakdown: ‘Google Ads: 250 orders, $10,000 revenue. Facebook: 180 orders, $8,000 revenue. Organic: 400 orders, $15,000 revenue.’
• Customer journey for single order shows: ‘Google Ads click → product page → category page → cart → checkout → order’
• Custom parameter ‘promo_code’ is tracked; analytics show ‘promo_code=SUMMER20: 100 orders, $4,000 revenue’
• Pixel firing test in admin shows: ‘Facebook Pixel: ✓ Fired. Payload: {pixel_id: 123456, order_id: abc, email: customer@example.com}’
• First-click and last-click attribution models both show in analytics; data is split correctly between them
• Order analytics export to CSV includes attribution source, medium, campaign for each order

Risks

Session tracking reliability: if session cookie is blocked, attribution is lost; educate merchant on first-party cookie setup. UTM parameter malformation: if utm_source contains typo, analytics split incorrectly; normalize on save. Pixel firing failures: if pixel code is malformed, conversion is not reported to ad platform; test and log all failures. Privacy concerns: if tracking captures PII, GDPR violations occur; only send anonymized email hash or order ID. Cross-domain tracking: if merchant has multiple domains (store, blog), session may not persist; educate on URL parameter passing. Attribution model complexity: if merchant doesn’t understand first-click vs. last-click, metrics may be misinterpreted; educate in UI. Paid tier confusion: paid module offers multi-touch attribution; core offering only first/last may seem limiting; document clearly.

Commercial context

The anchor is what the nearest equivalent charges on Shopify or Magento today. It is context for a pricing decision, not the decision.

---

Generated from the commerce plan. See docs/COMMERCE-PLAN.md for the full catalogue and ../../AI-GUIDE.md for how to work on this repository.