shopify-admin-marketing-consent-report

用途

该技能扫描所有客户记录，报告电子邮件和短信营销同意状态的分布情况（已订阅、已退订、待确认、从未询问）。可用于合规审计、GDPR/CAN-SPAM 审查，以及了解可触达的营销受众规模。只读——不执行任何变更操作。

前置条件

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

参数

参数	类型	必填	默认值	说明
store	string	是	—	商店域名（例如 mystore.myshopify.com）
channel	string	否	both	要审计的同意渠道：email、sms 或 both
format	string	否	human	输出格式：human 或 json

安全性

只读技能——不执行任何变更操作，可随时安全运行。

工作流程

操作：customers — 查询
- 输入：first: 250，选择 emailMarketingConsent { marketingState, consentUpdatedAt }、smsMarketingConsent { marketingState, consentUpdatedAt }、分页游标
- 预期输出：所有客户的同意状态；分页直到 hasNextPage: false
按渠道统计各同意状态的客户数量
计算：可触达受众（已订阅）、风险中（待确认）、不可触达（已退订/从未询问）

GraphQL 操作

# customers:query — validated against api_version 2025-01
query MarketingConsentAudit($after: String) {
  customers(first: 250, after: $after) {
    edges {
      node {
        id
        displayName
        defaultEmailAddress {
          emailAddress
        }
        emailMarketingConsent {
          marketingState
          consentUpdatedAt
          marketingOptInLevel
        }
        smsMarketingConsent {
          marketingState
          consentUpdatedAt
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

会话跟踪

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

开始时输出：

╔══════════════════════════════════════════════╗
║  SKILL: Marketing Consent 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（默认）：

══════════════════════════════════════════════
MARKETING CONSENT REPORT
  Total customers: <n>

  Email Marketing:
    Subscribed:    <n>  (<pct>%)  ← addressable
    Unsubscribed:  <n>  (<pct>%)
    Pending:       <n>  (<pct>%)
    Not asked:     <n>  (<pct>%)

  SMS Marketing:
    Subscribed:    <n>  (<pct>%)
    Unsubscribed:  <n>  (<pct>%)
    Not asked:     <n>  (<pct>%)
  Output: consent_audit_<date>.csv
══════════════════════════════════════════════

对于 format: json，输出：

{
  "skill": "marketing-consent-report",
  "store": "<domain>",
  "total_customers": 0,
  "email": { "subscribed": 0, "unsubscribed": 0, "pending": 0, "not_asked": 0 },
  "sms": { "subscribed": 0, "unsubscribed": 0, "not_asked": 0 },
  "output_file": "consent_audit_<date>.csv"
}

输出格式

CSV 文件 consent_audit_<YYYY-MM-DD>.csv，包含列： customer_id, email, email_marketing_state, email_consent_updated_at, sms_marketing_state, sms_consent_updated_at

错误处理

错误	原因	恢复方式
THROTTLED	超出 API 速率限制	等待 2 秒，最多重试 3 次
No customers	空商店	以 0 结果退出

最佳实践

“已订阅”是你的可触达营销受众——订阅率低可能表明结账时的选择加入不够醒目。
“待确认”表示客户提供了电子邮件但尚未确认同意——这在双重选择加入流程中很常见。
在重大营销活动前运行，以获取可触达受众的准确数量；如果你的 ESP 有未同步回 Shopify 的额外退订，它会显示不同的数字。
GDPR 合规提示：欧盟客户中 marketingOptInLevel: SINGLE_OPT_IN 的客户，根据你的处理法律依据，可能需要重新同意活动。