本文要点
- Shopify 于 2026 年 8 月 10 日开放 shop_campaign_insights，可通过现有 shopifyqlQuery 查询活动与分群表现。
- 已有 read_reports scope 且能查询 ShopifyQL 的应用无需新增 scope，但仍要确认商户授权和当前 token 是否有效。
- 可用指标包括广告花费、销售额、订单、ROAS、平均订单价值和平均获客成本，时间粒度从小时到年。
- 时间维度按商店时区解释；跨系统对账前必须统一日期边界、币种、归因窗口和活动筛选。
- 上线前先用单活动、短时间窗核对总数、空值和解析错误，再逐步接入缓存、分页和可视化。
先说结论：谁需要这项更新
如果你的应用已经用 ShopifyQL 做销售或营销报表，现在可以把 Shop Campaigns 数据放进同一查询链路。目标不是复制后台数字，而是让授权商户在应用中按活动、客户分群和时间查看表现。
不使用 Shop Campaigns、没有 read_reports 授权，或只需要后台手工查看的团队不必为此改代码。先确认业务确有持续报表需求。
旧方式与新 schema 有什么差别
此前应用无法通过这个专用 schema 直接查询 Shop Campaigns 表现。现在使用已有 shopifyqlQuery 字段并把数据源指向 shop_campaign_insights，即可读取活动级和分群级指标。
这不是新的营销归因规则，也不会自动修复历史报表。新能力只是开放查询入口；指标含义、商户资格和数据是否存在仍以 Shopify 返回为准。
权限和接入前检查
先确认应用已有 read_reports scope、当前访问令牌仍代表目标商店，并且商户实际使用 Shop Campaigns。官方说明已有 ShopifyQL 集成不需要新增 scope，但首次接入仍应在测试商店验证授权错误和空数据。
记录 Admin GraphQL API 版本、查询文本、商店标识和 request ID。不要把访问令牌写入浏览器日志、教程或工单；401/403 应先查授权与 scope，而不是反复重试。
查询与字段怎么组织
从 shop_campaign_insights 选择少量维度和指标开始，例如活动名称、日期、广告花费、销售额、订单、ROAS、平均订单价值和平均获客成本。先限定一个活动和短日期范围，确认列名、类型与空值，再扩大范围。
不要预设所有指标都能相加。比率和平均值应从官方口径或基础量重新计算；分群行与活动总计也不能混在同一汇总层级。对解析错误要读取 shopifyqlQuery 返回的 parseErrors。
商店时区是最容易漏掉的边界
Shopify 明确说明时间维度使用商店时区，且粒度可从小时到年。报表服务若统一存为 UTC，必须同时保存商店时区和原始时间维度，避免跨日、夏令时或月末对账错位。
与广告平台或财务系统比较前，先统一日期边界、币种、退款处理、归因窗口和活动状态。数字不一致时逐项缩小范围，不要直接用一个修正系数覆盖差异。
上线前的验证清单
选择一个商户、一个活动和一个完整日期段，把查询结果与 Shopify 可见报表逐项核对。检查列类型、空值、零值、重复行、时间边界、币种和总计，并保留查询与对账证据。
灰度阶段监控 GraphQL 错误、parseErrors、空结果比例、查询耗时和缓存命中。出现字段缺失、指标跳变或授权异常时停止扩量，回退到旧报表并保留原始响应。
网络错误与数据错误要分开
401、403 和 ShopifyQL 解析错误通常属于授权或查询层；DNS、TLS、连接超时才属于网络层。可先参考<a href="/resources/ai-api-key-base-url-model-guide">API Key、Base URL 与错误分层方法</a>，有明确网络证据时再看<a href="/resources/proxy-connection-troubleshooting-checklist">代理连接排查清单</a>。
跨境团队需要稳定访问 Shopify 开发文档和后台时，可以 <a href="/" target="_blank" rel="noopener noreferrer">访问 PuppyIP 官网</a>了解固定网络出口。网络出口不能获得商户授权、read_reports scope 或改变数据口径。
资料来源
常见问题
查询 Shop Campaigns 数据需要什么权限？
需要 read_reports scope，并使用授权商户的有效访问令牌。已有 ShopifyQL 集成通常不需要新增 scope。
shop_campaign_insights 能查哪些指标？
官方列出广告花费、销售额、订单、ROAS、平均订单价值和平均获客成本，并可按活动、客户分群和时间维度查询。
报表使用哪个时区？
时间维度按商店时区解释。与 UTC 数据仓库或广告平台对账时必须显式转换并保留原时区。
为什么查询返回空结果？
依次确认商户是否使用 Shop Campaigns、授权是否有效、日期与筛选是否命中，再检查 parseErrors；空结果不应直接当作零。
ROAS 和平均值可以直接跨活动相加吗？
不应直接相加。比率和平均值应按基础量及官方口径重新计算，避免活动总计与分群行重复汇总。
代理能解决 read_reports 权限错误吗？
不能。代理只影响连接路径，不能增加 OAuth scope 或商户授权；401/403 应先检查应用权限。