/shopify-admin-referral-source-attribution

name: shopify-admin-referral-source-attribution
role: marketing
description: "Read-only: parses each order's landing site and referrer URL to break down orders, revenue, and AOV by traffic source — direct, organic, paid, social, email, or referral domain."
toolkit: shopify-admin, shopify-admin-execution
api_version: "2025-01"
graphql_operations:
  - orders:query
status: stable
compatibility: Claude Code, Cursor, Codex, Gemini CLI

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

• Authenticated Shopify CLI session: `shopify store auth --store <domain> --scopes read_orders`
• API scopes: `read_orders`

Parameters

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | store | string | yes | — | Store domain (e.g., mystore.myshopify.com) | | format | string | no | human | Output format: `human` or `json` | | days_back | integer | no | 30 | Lookback window in days | | min_orders | integer | no | 1 | Minimum orders per source to include in the human-readable summary | | group_by | string | no | category | Grouping level: `category` (direct/organic/paid/social/email/referral), `domain` (raw referrer host), or `utm_source` (UTM param value) | | include_utm | bool | no | true | When true, parse `utm_source`, `utm_medium`, `utm_campaign` from `landingPageUrl` query string |

Safety

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

Workflow Steps

1. **OPERATION:** `orders` — query **Inputs:** `query: "created_at:>='<NOW - days_back days>'"`, `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`

2. For each order, derive a normalized source:

• If `customerJourneySummary.firstVisit.utmParameters.source` is set → use it (strongest signal)
• Else parse UTM params from `landingPageUrl` query string when `include_utm: true`
• Else extract host from `referrerUrl` and map to a category:
• empty/null → `direct`
• google.com / bing.com / duckduckgo.com → `organic-search`
• googleads/doubleclick → `paid-search`
• facebook.com / instagram.com / tiktok.com / x.com / twitter.com / pinterest.com / youtube.com → `social-<host>`
• mail/gmail/outlook hosts → `email`
• any other host → `referral-<host>`

3. Aggregate by the chosen `group_by` dimension:

• orders count
• revenue = Σ `totalPriceSet.shopMoney.amount`
• AOV = revenue / orders
• new-customer % (orders where `customer.numberOfOrders == 1` divided by total in source)

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_<YYYY-MM-DD>.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

| Error | C