UTM Tracking & Campaign Attribution

Overview

The UTM tracking system in TanStack Ship captures marketing parameters from incoming traffic sources, persists them to user sessions, and enables automated campaign attribution and offer matching. Every user journey can be traced back to its original marketing touchpoint, providing complete visibility into campaign ROI.

As part of the platform, the UTM module integrates with the campaign and offer system for automatic discount matching, the short links system for trackable URLs, and the attribution analytics dashboard for data-driven marketing decisions.

UTM Data Pipeline

The tracking system captures marketing parameters at the first touchpoint and carries them through the entire user lifecycle:

Design Philosophy

The UTM tracking system is built on three design principles:

• Passive Capture, Zero Friction — UTM parameters are captured silently during page load, requiring no user action or opt-in. The system works in the background, collecting attribution data without impacting the user experience.
• Dual Attribution Model — Both first-touch (original acquisition channel) and last-touch (conversion trigger) attribution are stored. This provides a complete picture of the customer journey from first click to final conversion.
• Privacy-Conscious by Default — UTM data is treated as first-party analytics, stored securely and never shared with third parties. No external tracking scripts are required — everything happens within the platform's own infrastructure. Unlike Google Analytics or HubSpot — which require embedding third-party JavaScript tags and rely on external cookie synchronization for cross-session attribution — our UTM capture runs entirely on your own infrastructure with first-party cookies, keeping all marketing data under your control.

Core Capabilities

UTM Parameter Capture

The system captures UTM parameters from URL query strings on every page load, ensuring no attribution data is lost:

• Captured Parameters — utm_source, utm_medium, utm_campaign, utm_term, utm_content
• Referrer Tracking — HTTP referrer header is captured alongside UTM data for additional context
• Client Capture — Parameters are captured on the client side during page load
• Fallback Behavior — Multiple capture mechanisms ensure parameters are recorded even in edge cases

Example — A typical UTM-tagged URL:

https://yourplatform.com/pricing?utm_source=google&utm_medium=cpc&utm_campaign=summer2024

When a user arrives through this URL, the system captures:

• Source: google
• Medium: cpc (cost per click)
• Campaign: summer2024

Client-side UTM access example:

import { useQuery } from '@tanstack/react-query'

function CampaignBanner() {
  const { data } = useQuery({
    queryKey: ['utm-attribution'],
    queryFn: () =>
      fetch('/api/utm/session').then((r) => r.json()) as Promise<{
        utmSource: string | null
        utmMedium: string | null
        utmCampaign: string | null
      }>,
  })

  if (!data?.utmCampaign) return null

  return (
    <div className="rounded-md bg-gradient-to-r from-primary/10 to-primary/5 p-4 text-center">
      <p>Welcome! You found us through {data.utmSource}.</p>
      <p className="text-muted-foreground text-sm">
        Campaign: {data.utmCampaign}
      </p>
    </div>
  )
}

UTM Storage & Persistence

Once captured, UTM data follows the user throughout their journey:

• First-Touch Attribution — The first set of UTM parameters detected for a user is stored permanently
• Last-Touch Attribution — The most recent UTM parameters before conversion are also recorded
• Session Persistence — Parameters persist via cookies with a configurable duration (30 days by default)
• Account Linking — When a user registers, the captured UTM data is saved to their account record
• Conversion Association — All future conversions (subscriptions, purchases) are attributed to the stored UTM data

UTM Builder Tool

The UTM Builder provides a user-friendly interface for creating campaign URLs. It guides you through:

1. Enter your destination URL
2. Fill in UTM parameters (source, medium, campaign, term, content)
3. Optionally shorten the URL with the short link system
4. Preview and copy the final URL for distribution

The builder validates parameter formats and suggests naming conventions to keep your data clean.

Automatic Offer Matching

When combined with the campaign system, UTM parameters trigger automatic pricing adjustments:

This enables sophisticated marketing strategies without requiring users to manually enter coupon codes.

Best Practices

Consistent UTM Naming

Use a consistent naming convention: {source}_{medium}_{campaign} — for example, twitter_social_summer2024. This enables better filtering and reporting in the analytics dashboard. A standardized naming convention prevents fragmentation — having both google and Google as source values splits your data.

Essential Parameters Only

Focus on the five core UTM parameters (source, medium, campaign, term, content). Adding custom query parameters beyond these five can reduce reporting clarity.

Track Both First and Last Touch

First-touch attribution reveals which channel originally acquired the user, while last-touch attribution shows what drove conversion. The system stores both for complete analysis.

Test Before Launch

Before launching a campaign, test your UTM links by simulating a visit. Verify that the parameters are captured and that any associated offers appear during checkout.

FAQ

How does the system capture UTM parameters? UTM parameters are captured from URL query strings on every page load. Parameters persist in cookies with a configurable TTL (default 30 days) and are saved to the user's database record upon registration.

Are UTM parameters stored permanently? Yes. Once captured, UTM data is persisted to the user's database record and associated with all future conversions.

Can I use UTM parameters for automatic discounts? Yes. When combined with the campaign and offer system, UTM parameters can trigger automatic discount matching during checkout without requiring coupon codes.

What happens to users without UTM parameters? Visits without UTM parameters are categorized as "direct/none" traffic and tracked separately. These appear in analytics as unassigned traffic.

How are UTM parameters from different sessions handled? The system stores both first-touch (earliest detected) and last-touch (most recent) UTM data. This gives you insight into both acquisition channels and conversion triggers.

Configuration

UTM tracking works out of the box — no special configuration required. The capture mechanism is included in the application root and activates automatically.

For UTM-based offer matching, configure campaigns in the admin dashboard with the desired offer and UTM parameters.

Integration Points

• Campaigns & Offers — UTM parameters trigger automatic offer matching during checkout
• Short Links — UTM parameters can be embedded in short link URLs for trackable distribution
• Attribution Analytics — Full attribution reporting dashboard with revenue tracking
• Click Analytics — Track click-through rates on campaign links