shopify-admin-order-attribution-report

用途

该技能拉取近期订单，从每个订单的 landingPageUrl 查询字符串中提取 UTM 参数，并按 utm_source、utm_medium、utm_campaign 汇总收入、订单数和平均订单价值（AOV）。它直接基于 Shopify 一方订单数据构建营销归因报告，无需外部分析工具。只读，不执行任何变更。

前置条件

已认证的 Shopify CLI 会话：shopify store auth --store <domain> --scopes read_orders
API 权限范围：read_orders

参数

参数	类型	必填	默认值	说明
store	string	是	—	店铺域名（例如 mystore.myshopify.com）
days_back	integer	否	30	归因订单的回溯窗口
group_by	string	否	source	主要分组维度：source、medium、campaign 或 source_medium
min_orders	integer	否	1	报告中每组包含的最小订单数
include_organic	bool	否	true	为 false 时，从细分中排除没有 UTM 参数的订单
format	string	否	human	输出格式：human 或 json

安全性

只读技能，不执行任何变更，可随时安全运行。归因准确性取决于店铺前台是否将 UTM 参数传递到结账流程——绕过前台的订单（POS、草稿订单、订阅）不会有落地页 URL。

工作流程

操作：orders — 查询。输入：query: "created_at:>='<NOW - days_back days>' financial_status:paid"，first: 250，选择 landingPageUrl、referrerUrl、customerJourneySummary、totalPriceSet、分页游标。预期输出：窗口内所有已付款订单及其落地页 URL；分页直到 hasNextPage: false。
对每个订单，解析 landingPageUrl 查询字符串，提取 utm_source、utm_medium、utm_campaign、utm_term、utm_content。没有 UTM 参数的订单在 include_organic: true 时归入 (direct/organic) 桶。
按 group_by 维度聚合：汇总订单数、汇总收入（以店铺货币计），计算 AOV = 收入 / 订单数。
按收入降序排列分组；过滤掉低于 min_orders 的分组。

GraphQL 操作

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

会话跟踪

Claude 必须在每个阶段输出以下内容，这是强制要求。

开始时输出：

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

每个步骤后输出：

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

完成时输出：

对于 format: human（默认）：

══════════════════════════════════════════════
ORDER ATTRIBUTION REPORT  (<days_back> days)
  Orders attributed:   <n>
  Total revenue:       $<amount>
  Untagged (direct):   <n>  (<pct>%)

  Top sources by revenue:
    <source>     Orders: <n>   Revenue: $<n>   AOV: $<n>
    <source>     Orders: <n>   Revenue: $<n>   AOV: $<n>
  Output: attribution_report_<date>.csv
══════════════════════════════════════════════

对于 format: json，输出：

{
  "skill": "order-attribution-report",
  "store": "<domain>",
  "period_days": 30,
  "group_by": "source",
  "orders_attributed": 0,
  "total_revenue": 0,
  "currency": "USD",
  "groups": [
    { "key": "google", "orders": 0, "revenue": 0, "aov": 0 }
  ],
  "output_file": "attribution_report_<date>.csv"
}

输出格式

CSV 文件 attribution_report_<YYYY-MM-DD>.csv，包含列：group_key, utm_source, utm_medium, utm_campaign, orders, revenue, aov, currency, pct_of_revenue

错误处理

错误	原因	恢复方式
THROTTLED	超出 API 速率限制	等待 2 秒，最多重试 3 次
landingPageUrl is null	通过 POS、草稿或订阅下单	归入 (direct/organic)，单独计数
Malformed query string	手动或部分 UTM 标记	跳过解析失败，视为直接流量，记录数量
customerJourneySummary access denied	店铺套餐不开放此字段	回退到仅解析 landingPageUrl

最佳实践

使用 group_by: source_medium 区分付费流量（google/cpc）与自然流量（google/organic）。
(direct/organic) 占比过高通常意味着付费活动缺少 UTM 标记——应修复活动 URL，而不是报告。
活动期间每周运行以跟踪归因漂移；稳定状态报告每月运行。
将此处收入与广告平台的广告支出交叉比对，计算真实 ROAS——本技能仅提供订单侧分子。
对于多触点归因，还可展示 customerJourneySummary.firstVisit 与 lastVisit，以比较首次点击与末次点击模型。