Attribution Analytics

Overview

The attribution analytics dashboard in TanStack Ship provides comprehensive visibility into how your marketing channels drive conversions and revenue. By tracing user journeys back to their original UTM parameters — source, medium, campaign, and content — the system reveals which campaigns, traffic sources, and marketing channels deliver the highest return on investment.

As part of the platform, the attribution analytics system processes data from the UTM tracking module (capturing user touchpoints at signup), the billing system (tracking which subscriptions convert), and the short links module (measuring click-through attribution). This unified view enables data-driven marketing decisions across all acquisition channels.

Attribution Pipeline

The attribution system traces each conversion back to its marketing origin through a structured data pipeline:

Design Philosophy

The attribution analytics system is guided by three core principles:

• Data-Driven Decision Making — Every marketing KPI (attributed conversions, revenue, CPA, conversion rate) is quantified and visualized. Decisions are based on measurable outcomes rather than intuition, enabling objective budget allocation across channels.
• Last-Touch with First-Touch Context — The default last-touch attribution model gives full credit to the most recent UTM parameters before conversion. However, first-touch data is preserved alongside, providing context for the original acquisition channel.
• Transparent Measurement — All attribution logic is deterministic and auditable. Every conversion can be traced back to its source parameters, enabling precise ROI calculation and eliminating black-box marketing analytics. Unlike Triple Whale or Mixpanel — which rely on probabilistic attribution models and third-party data enrichment — our system uses deterministic first-party attribution based on actual UTM parameters captured at each touchpoint, ensuring every metric is fully auditable.

Core Capabilities

Attribution Dashboard

The main analytics dashboard provides a comprehensive view of marketing performance:

• KPI Cards — Key performance indicators including total attributed conversions, attributed revenue, average conversion rate, and cost per acquisition (CPA)
• Trend Charts — Line charts showing attribution trends over configurable time periods with daily, weekly, or monthly aggregation
• Source Breakdown — Traffic and conversion distribution by UTM source (google, twitter, linkedin, facebook, direct, email)
• Campaign Rankings — Top-performing campaigns ranked by conversion count, total attributed revenue, and ROI percentage
• Detail Data Table — Granular attribution data with multi-column filtering, sortable columns, and CSV export

Example — Dashboard KPI summary:

Programmatic analytics access example:

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

function AttributionMetrics() {
  const { data } = useQuery({
    queryKey: ['attribution-summary'],
    queryFn: () =>
      fetch('/api/attributions/summary').then((r) => r.json()) as Promise<{
        attributedConversions: number
        attributedRevenue: number
        avgConversionRate: number
        cpa: number
      }>,
  })

  return (
    <div className="rounded-lg border p-4">
      <h3 className="mb-3 font-semibold">Attribution KPIs</h3>
      <dl className="grid grid-cols-2 gap-4">
        <div>
          <dt className="text-sm text-muted-foreground">Conversions</dt>
          <dd className="text-xl font-bold">{data?.attributedConversions.toLocaleString() ?? '—'}</dd>
        </div>
        <div>
          <dt className="text-sm text-muted-foreground">Revenue</dt>
          <dd className="text-xl font-bold">${data?.attributedRevenue.toLocaleString() ?? '—'}</dd>
        </div>
        <div>
          <dt className="text-sm text-muted-foreground">Conv. Rate</dt>
          <dd className="text-xl font-bold">{data?.avgConversionRate != null ? `${data.avgConversionRate}%` : '—'}</dd>
        </div>
        <div>
          <dt className="text-sm text-muted-foreground">CPA</dt>
          <dd className="text-xl font-bold">${data?.cpa.toFixed(2) ?? '—'}</dd>
        </div>
      </dl>
    </div>
  )
}

Multi-Source Attribution Reporting

Attribution data can be sliced and analyzed across multiple dimensions:

• UTM Source — Identify which traffic sources (search engines, social media, referral sites) generate the most valuable conversions
• UTM Medium — Compare performance across traffic types: CPC (paid search), social (organic social), email, referral
• UTM Campaign — Evaluate individual campaign performance to allocate budget effectively
• UTM Content — Analyze specific ad variations or link variants at the granular level
• Cross-Section Analysis — Combine dimensions for deeper insights, such as conversion performance by source × campaign or medium × content

Conversion Tracking Across the User Lifecycle

The system tracks attributed conversions at every stage of the user journey:

• User Registration — New sign-ups are attributed to the UTM parameters present at registration
• Subscription Purchases — When a user subscribes, the conversion is credited to the acquisition source
• Credit Purchases — Credit point purchases are tracked as conversion events with full attribution detail
• Configurable Events — Additional conversion events can be defined to track specific business metrics

Each conversion records the complete attribution chain — original UTM parameters, user ID, conversion type, monetary value, and timestamp — enabling accurate ROI calculation per marketing channel.

Trend Analysis and Performance Comparison

Visualize how attribution metrics evolve over time:

• Period-over-Period Comparison — Compare metrics between two date ranges to measure growth or decline
• Cohort Analysis — Group conversions by acquisition period to analyze long-term value by channel
• Seasonal Trend Detection — Identify recurring patterns tied to seasonal events and campaigns
• Custom Date Ranges — Flexible date filtering with presets (last 7 days, this month, last month, quarter to date, year to date)

Best Practices

Consistent UTM Naming Conventions

Establish and enforce a consistent UTM naming convention across all marketing initiatives. Standardize source names (use google not Google or google.com), medium classifications (cpc, social, email, referral), and campaign naming patterns ({channel}-{campaign}-{date}). Consistency ensures that attribution data aggregates correctly without fragmented dimension values.

Understand Your Attribution Model

The system uses a last-touch attribution model by default — the most recent UTM parameters before conversion receive full credit. This may overvalue bottom-of-funnel channels. For a complete picture, cross-reference with campaign and offer data to understand assisted conversions.

Campaign Parameter Hygiene

Always include complete UTM parameters in campaign URLs. A campaign without utm_source and utm_medium will be categorized as "direct/none" and excluded from meaningful reporting. Use the UTM builder to ensure complete parameter sets.

Regular Performance Reviews

Schedule regular attribution review cycles — weekly for active campaigns, monthly for strategic planning. Use period-over-period comparison to identify positive trends and negative shifts.

Frequently Asked Questions

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 30-day default expiration and are saved to the user's database record upon registration.

What attribution model does the system use? The system uses a last-touch attribution model by default. The most recent UTM parameters before conversion receive full credit. Custom models can be configured.

Can I track conversions beyond subscriptions and registrations? Yes. The system supports configurable conversion events. Define additional types to track specific business metrics such as feature adoption, demo requests, or content downloads.

How far back does attribution data go? Attribution data is retained indefinitely. The dashboard supports arbitrary date range selection for historical trends and year-over-year comparisons.

How does the system handle direct traffic? Visits without UTM parameters are categorized as "direct/none" and tracked separately, helping you distinguish between organic and campaign-driven growth.

Can I export data for external analysis? Yes. The dashboard includes CSV export that downloads filtered attribution data for analysis in spreadsheets or BI tools.

How does CPA calculation work? CPA is calculated by dividing total campaign spend by attributed conversions. Cost data can be imported per campaign through the admin interface.

Configuration

The attribution analytics dashboard is accessed from the admin panel and requires:

• Active UTM tracking (included by default)
• User registration and conversion events with UTM attribution recording
• Admin role access to the dashboard

No additional environment variables are required for core attribution functionality.

Integration Points

The attribution analytics system integrates with these platform modules:

• UTM Tracking — Attribution data originates from the UTM capture system
• Billing System — Subscription purchases are attributed conversions tied to acquisition sources
• Campaign Management — Campaign performance is measured through attribution
• Short Links — Short link clicks feed into attribution data
• Credit System — Credit purchases are tracked as conversion events
• Email Marketing — Email campaign click-throughs are attributed through UTM parameters