Conversion Tracking

Free — GPL coresize Mplanned, not built

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

A core feature that logs every step of the customer journey (product view, cart add, checkout step, payment method choice, order completion) and gives merchants funnel analysis without external tools. Merchants see exactly where checkout friction exists and test improvements.

The problem

A Portuguese fashion merchant has 10,000 visitors per month but only 200 orders (2% conversion). She doesn’t know why. Do customers drop at cart? At checkout? At payment method selection? She’s been guessing for 6 months. She needs to see the funnel to fix it.

What it does

• Event capture: auto-log view, add-to-cart, begin-checkout, select-payment, order-placed
• Funnel visualization: show % of users who complete each step (1000 viewed → 500 added to cart → 200 checked out → 100 ordered)
• Micro-conversion tracking: discount code usage, wish-list save, review submission, product comparison
• Time-to-purchase: how long from first visit to order (same day? 3 days? 2 weeks?)
• Abandonment analysis: which products are added to cart but never purchased?
• Cohort analysis: segment users by acquisition date, traffic source, geography; compare conversion rates
• Admin UI: funnel chart (week-over-week), top abandon points, conversion rate by product
• Alerts: if conversion rate drops >20% week-over-week, alert merchant
• Custom events: merchant can configure tracking for custom events (e.g., ‘viewed blog post’, ‘tried coupon’)

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.

• A/B testing or multivariate testing—separate feature (can build on top of conversion-tracking)
• Session replay or heatmaps (showing exactly what users clicked)—out of scope (privacy-heavy)
• Predictive churn (forecasting which customers will abandon)—out of scope
• Cart recovery email (reminding about abandoned cart)—separate email marketing feature
• Attribution (which channel led to order)—GA4 handles this; we just track events

Data model

New: ConversionEvent(id, shopId, customerId, event_type, product_id, timestamp, session_id, source_url); extend Order: first_visit_date, funnel_path (array of events). No core migration; ConversionEvent is plugin-level table.

API

• POST /conversions/track — log a conversion event (called by frontend)
• GET /conversions/funnel/:period — return funnel steps + completion rates
• GET /conversions/abandonment — return products added-to-cart but not purchased
• GET /conversions/cohort-analysis — compare conversion rates by cohort (traffic source, date, geo)
• GET /conversions/time-to-purchase — histogram of days from first visit to order
• POST /conversions/alerts/subscribe — alert merchant if conversion rate drops

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

Admin

Conversion dashboard: funnel chart (view → cart → checkout → payment → order, with % completion), top abandon points (e.g., 40% drop at payment method), conversion rate trend (week/month), product-level abandonment (which products are abandoned most?), cohort comparison

The seam — why this is core

Core owns: event logging infrastructure, order/cart data. Paid pack owns: real-time funnel calculations, cohort segmentation algorithms, predictive analytics (churn forecasting).

Core owns the interface + honest conversion logger; analytics is infrastructure, not a credential or support commitment.

Dependencies

• order schema (first_visit_date field)
• frontend event logging (events must be sent from Next.js storefront)

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 product page, adds to cart, starts checkout, drops at payment step; ConversionEvent logs all 4 steps
• Funnel for Sept 2025 shows: 1000 views → 500 cart adds (50%) → 200 checkouts (40%) → 100 orders (50%)
• Abandonment report shows ‘Red Dress’ product: added to cart 80 times, purchased 20 times (75% abandon rate)
• Cohort analysis compares email vs organic traffic: email 5% conversion, organic 3%
• Time-to-purchase histogram shows: 60% of orders placed same day, 20% within 3 days, 20% within 2 weeks
• Conversion rate drops from 3% to 2.4% week-over-week; merchant receives alert ‘Conversion rate down 20%’
• Tracking event is logged and appears in funnel within 30 seconds (near real-time)

Risks

Frontend event logging fails (JS error blocks tracking)—funnel data is incomplete. Merchants misinterpret abandonment (‘75% abandon’ doesn’t mean 75% lost revenue). If funnel alerts fire too often (daily noise), merchants ignore them. Session ID collision: same user appears as 2 sessions—funnel is wrong. Tracking too many events = privacy risk + storage cost.

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.