shopify-admin-post-purchase-survey-trigger

用途

本技能通过筛选在 survey_min_days 到 survey_max_days 天前完成履约、未退款、未取消、（可选）且客户已同意营销的订单，来构建购后调查活动的收件人名单。输出为干净的收件人列表，可直接载入邮件或短信自动化流程。全程只读，不执行任何变更。

前置条件

已认证的 Shopify CLI 会话：shopify store auth --store <domain> --scopes read_orders,read_customers,read_fulfillments

API 权限范围：read_orders、read_customers、read_fulfillments

参数

store（string，必填，无默认）：店铺域名（例如 mystore.myshopify.com）
survey_min_days（integer，可选，默认 7）：履约后最早可调查的天数（留出配送与初次使用时间）
survey_max_days（integer，可选，默认 14）：履约后最晚可调查的天数（约两周后回忆会衰减）
marketing_consent_only（bool，可选，默认 true）：仅保留 marketingState: SUBSCRIBED 的客户
exclude_repeat_recipients_days（integer，可选，默认 90）：跳过在此窗口内已进入过调查名单的客户（由调用方跟踪）
format（string，可选，默认 human）：输出格式，human 或 json

安全性

本技能为只读，不执行任何变更。它生成收件人名单；实际发送调查交由调用方通过自己的邮件或短信平台完成。为符合同意规则，促销类调查应保持 marketing_consent_only: true。

工作流程

计算时间窗口：latest_fulfilled_at = NOW - survey_min_days；earliest_fulfilled_at = NOW - survey_max_days
OPERATION: orders — 查询输入：query: "fulfillment_status:fulfilled financial_status:paid -status:cancelled updated_at:>=<earliest_fulfilled_at>"，first: 250，select displayFulfillmentStatus、displayFinancialStatus、cancelledAt、fulfillments { createdAt, displayStatus, deliveredAt }、refunds { id, createdAt }、customer { id, defaultEmailAddress { emailAddress, marketingState }, displayName, locale }、分页游标预期输出：所有候选订单；持续分页直到 hasNextPage: false
使用最早的履约 createdAt 按调查窗口过滤订单：

若 fulfilled_at 不在 [earliest_fulfilled_at, latest_fulfilled_at] 内则跳过
若 cancelledAt != null 则跳过
若存在任何退款（全额或部分）则跳过
若 customer 为 null（无邮箱的访客订单）则跳过
若 marketing_consent_only: true 且 marketingState != SUBSCRIBED 则跳过

按客户邮箱去重——同一客户的多个订单合并为一次调查邀请
输出收件人名单

GraphQL 操作

orders:query — 已针对 api_version 2025-01 校验

query SurveyEligibleOrders($query: String!, $after: String) { orders(first: 250, after: $after, query: $query) { edges { node { id name createdAt cancelledAt displayFinancialStatus displayFulfillmentStatus totalPriceSet { shopMoney { amount currencyCode } } fulfillments(first: 5) { id createdAt displayStatus deliveredAt } refunds { id createdAt } customer { id displayName locale defaultEmailAddress { emailAddress marketingState } } } } pageInfo { hasNextPage endCursor } } }

输出格式

CSV 文件 post_purchase_survey_<YYYY-MM-DD>.csv，包含列：customer_id、email、name、locale、order_name、order_total、currency、fulfilled_at、delivered_at、days_since_fulfilled

错误处理

THROTTLED：API 速率限制超限。等待 2 秒，最多重试 3 次。
Order with multiple fulfillments：拆分发货。窗口计算使用最早的 createdAt；在 CSV 中标记 multi_fulfillment: true。
deliveredAt null：承运商未上报妥投。以 fulfillments.createdAt 作为替代（可能略有偏差）。
Customer with no email：仅手机号资料。跳过——调查活动假设使用邮件渠道。

最佳实践

在履约后 7–14 天发送调查：7 天足以完成配送与初次使用，14 天是回忆衰减前的最佳时点。
对于高客单价或需慎重考虑的品类（家具、电子产品），将 survey_max_days 延长至 30——客户形成意见较晚。
可搭配 customer-cohort-analysis，对比调查响应者与非响应者的留存率——活跃响应者通常是黏性最强的群体。
绝不要纳入已退款或已取消订单的客户——调查他们招来的是投诉，而非可行动的反馈。
按每日计划运行本技能，并将 CSV 直接接入邮件自动化；人工节奏会破坏时间窗口定位。

技能介绍

orders:query — 已针对 api_version 2025-01 校验