Referral Source Attribution

Purpose

Aggregates orders by their first-touch traffic source — extracted from each order's landingPageUrl, referrerUrl, and any UTM parameters embedded in the landing URL. Produces an attribution table showing orders, revenue, and AOV per source so merchants can see which channels are actually converting. Read-only — no mutations. Use when native Shopify analytics dashboards aren't granular enough or when you need to export raw attribution data for an external model.

Prerequisites

Parameters

Safety

> ℹ️ Read-only skill — no mutations are executed. Safe to run at any time.

Workflow Steps

Inputs: query: "created_at:>=''", first: 250, select id, name, createdAt, landingPageUrl, referrerUrl, customerJourneySummary { firstVisit { landingPage referrerUrl source sourceType utmParameters { source medium campaign term content } } }, totalPriceSet, customer { numberOfOrders }, pagination cursor

Expected output: Orders with their landing/referrer/UTM data; paginate until hasNextPage: false

GraphQL Operations

# orders:query — validated against api_version 2025-01
query OrdersForAttribution($query: String!, $after: String) {
  orders(first: 250, after: $after, query: $query) {
    edges {
      node {
        id
        name
        createdAt
        landingPageUrl
        referrerUrl
        totalPriceSet {
          shopMoney { amount currencyCode }
        }
        customer {
          id
          numberOfOrders
        }
        customerJourneySummary {
          firstVisit {
            landingPage
            referrerUrl
            source
            sourceType
            utmParameters {
              source
              medium
              campaign
              term
              content
            }
          }
          momentsCount {
            count
          }
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Session Tracking

Claude MUST emit the following output at each stage. This is mandatory.

On start, emit:

╔══════════════════════════════════════════════╗
║  SKILL: Referral Source Attribution          ║
║  Store: <store domain>                       ║
║  Started: <YYYY-MM-DD HH:MM UTC>             ║
╚══════════════════════════════════════════════╝

After each step, emit:

[N/TOTAL] <QUERY|MUTATION>  <OperationName>
          → Params: <brief summary of key inputs>
          → Result: <count or outcome>

On completion, emit:

For format: human (default):

══════════════════════════════════════════════
ATTRIBUTION REPORT  (<days_back> days, group: <group_by>)
  Orders analyzed:    <n>
  Total revenue:      $<amount>
  Sources detected:   <n>

  Top sources by revenue
  ─────────────────────────────────────────
  <source>            Orders: <n>  Revenue: $<n>  AOV: $<n>  New cust: <pct>%
  <source>            Orders: <n>  Revenue: $<n>  AOV: $<n>  New cust: <pct>%
  ...

  Output: attribution_<date>.csv
══════════════════════════════════════════════

For format: json, emit:

{
  "skill": "referral-source-attribution",
  "store": "<domain>",
  "period_days": 30,
  "group_by": "category",
  "totals": {
    "orders": 0,
    "revenue": 0,
    "currency": "USD"
  },
  "sources": [
    {
      "source": "<name>",
      "orders": 0,
      "revenue": 0,
      "aov": 0,
      "new_customer_pct": 0
    }
  ],
  "output_file": "attribution_<date>.csv"
}

Output Format

CSV file attribution_.csv with columns:

order_id, order_name, created_at, source, source_category, referrer_url, landing_page_url, utm_source, utm_medium, utm_campaign, revenue, is_new_customer

Error Handling

Best Practices