shopify-admin-customer-acquisition-cost-by-source

用途

按流量来源估算客户获取成本（CAC）。将归因到落地页/引荐来源的新客户订单数与每个来源可配置的广告支出输入相结合，回答：在来源 X 上每花费一美元，获取了多少新客户、单位成本是多少？该技能为只读，不执行任何变更，可随时安全运行。它为付费媒体预算重新分配提供数据基础。

主要能力

查询指定回溯窗口内的订单，提取客户归因与引荐信息。
按规范化来源对订单分组，解析顺序为：customerJourneySummary.firstVisit.source（若存在）→ 从 referrerUrl 解析域名 → 从 landingPageUrl 的 UTM 参数解析 utm_source → 归入 direct。
当 new_customers_only 为 true 时，丢弃 customer.numberOfOrders > 1 的订单，使每位客户只计一次。
按来源聚合：orders_count、new_customers_count、revenue_attributed。
与 ad_spend 映射连接：cac = ad_spend[source] / new_customers_count；无支出数据的来源报告 cac: null（自然流量/未归因）。
过滤掉 orders_count 小于 min_orders_per_source 的来源。
输出 CSV 文件 cac_by_source_<YYYY-MM-DD>.csv，列为 source, orders_count, new_customers_count, revenue_attributed, ad_spend, cac, currency。

使用方式

前置条件：已认证的 Shopify CLI 会话，命令为 shopify store auth --store <domain> --scopes read_orders,read_customers；API 作用域为 read_orders、read_customers。

参数：

store（字符串，必填）：店铺域名，例如 mystore.myshopify.com。
days_back（整数，可选，默认 30）：订单归因的回溯窗口。
ad_spend（对象，可选，默认 {}）：来源名称到店铺货币支出的映射，例如 {"google": 4500, "meta": 3200, "tiktok": 1800}。
new_customers_only（布尔，可选，默认 true）：是否仅将首单客户计为“已获取”。
min_orders_per_source（整数，可选，默认 5）：来源被报告所需的最小订单数。
format（字符串，可选，默认 human）：输出格式，human 或 json。

工作流程：

查询订单，输入 query: "created_at:>='<NOW - days_back days>'", first: 250，选择 customer { id, numberOfOrders }、customerJourneySummary { firstVisit { landingPage referrerUrl source } }、landingPageUrl、referrerUrl、totalPriceSet、分页游标；分页直到 hasNextPage: false。
按规范化来源对订单分组（解析顺序见上）。
若 new_customers_only 为 true，丢弃 customer.numberOfOrders > 1 的订单。
按来源聚合 orders_count、new_customers_count、revenue_attributed。
与 ad_spend 映射连接计算 cac。
按 min_orders_per_source 过滤。

GraphQL 操作（针对 api_version 2025-01 验证）：

query OrdersWithAttribution($query: String!, $after: String) {
  orders(first: 250, after: $after, query: $query) {
    edges {
      node {
        id
        name
        createdAt
        landingPageUrl
        referrerUrl
        customerJourneySummary {
          firstVisit {
            landingPage
            referrerUrl
            source
            sourceType
            utmParameters {
              source
              medium
              campaign
            }
          }
        }
        totalPriceSet {
          shopMoney {
            amount
            currencyCode
          }
        }
        customer {
          id
          numberOfOrders
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

会话跟踪：技能要求在开始、每步之后和完成时输出特定格式的文本。开始输出包含技能名、店铺域名和开始时间的框；每步之后输出 [N/TOTAL] <QUERY|MUTATION> <OperationName> 及参数和结果摘要；完成时按 format 输出人类可读报告或 JSON。

人类可读输出示例：

══════════════════════════════════════════════
CAC BY SOURCE  (<days_back> days)
  Orders analyzed:        <n>
  New customers acquired: <n>
  Total ad spend (input): $<amount>
  Blended CAC:            $<amount>

  By Source (sorted by CAC ascending):
    google      Customers: <n>  Spend: $<n>   CAC: $<n>
    meta        Customers: <n>  Spend: $<n>   CAC: $<n>
    direct      Customers: <n>  Spend: —      CAC: organic
    referral    Customers: <n>  Spend: —      CAC: organic

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

JSON 输出示例：

{
  "skill": "customer-acquisition-cost-by-source",
  "store": "<domain>",
  "period_days": 30,
  "orders_analyzed": 0,
  "new_customers": 0,
  "blended_cac": 0,
  "currency": "USD",
  "by_source": [],
  "output_file": "cac_by_source_<date>.csv"
}

适用场景

为付费媒体预算重新分配提供数据基础。
按来源评估新客户获取效率。
与 customer-cohort-analysis 配合，验证低 CAC 来源是否也产生高 LTV 客户。

限制

只读技能，不执行任何变更。
广告支出值由调用方提供，不拉取任何广告平台数据。
输出为估算 CAC；Shopify 的首次触点归因不捕获跨设备旅程，因此依赖浏览后转化（展示、视频）的来源会被低估。
报告为 direct 的来源常隐藏归因泄漏，需在得出结论前调查 UTM 标记和引荐策略。
提供广告支出时应与 days_back 窗口一致，窗口不匹配会产生误导性 CAC 数字。
错误处理：THROTTLED（API 速率限制）等待 2 秒重试最多 3 次；ad_spend 为空时报告订单/客户数且 cac: null；缺少 customerJourneySummary 时回退到 referrerUrl → landingPageUrl → direct；所有订单来自 direct 时可能为跟踪配置错误，应作为警告呈现。
建议每周重新运行以在活动变得无利可图之前捕捉 CAC 漂移。

技能介绍

用途

主要能力

使用方式

适用场景

限制