shopify-admin-discount-hygiene-cleanup

用途

该技能用于审计 Shopify 商店的折扣码目录，识别三类问题：已过期的折扣码、零兑换（零使用）的折扣码，以及重复的折扣码前缀。随着多次营销活动累积，折扣码会变得杂乱，导致后台难以管理。此技能可替代手动折扣清理流程，在 discount-ab-analysis 技能基础上增加了写入（删除）步骤。

前置条件

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

参数

store（string，必填）：商店域名，例如 mystore.myshopify.com
flag_expired（bool，选填，默认 true）：标记/删除已过结束日期的折扣码
flag_zero_usage（bool，选填，默认 true）：标记/删除超过 N 天且兑换数为 0 的折扣码
zero_usage_min_age_days（integer，选填，默认 30）：零使用标记的年龄阈值
dry_run（bool，选填，默认 true）：仅预览而不执行变更
format（string，选填，默认 human）：输出格式，human 或 json

安全提示

⚠️ discountCodeDelete 会永久删除折扣码，删除后无法恢复。已收到该码的顾客将发现其失效。建议先以 dry_run: true 运行，审查被标记的列表后再提交。删除前务必确认已过期折扣码未被仍在进行的邮件营销活动引用。

工作流程

OPERATION: discountNodes — 查询输入：first: 250、select discount { ... on DiscountCodeBasic { codes, usageLimit, asyncUsageCount, endsAt, status } }、分页游标预期输出：所有折扣码及其使用与过期数据；持续分页直到 hasNextPage: false
标记匹配以下条件的折扣：flag_expired（status = EXPIRED）和/或 flag_zero_usage（asyncUsageCount == 0 且创建时间早于 zero_usage_min_age_days 天前）
OPERATION: discountCodeDelete — 变更输入：id: <discount_node_id> 预期输出：deletedCodeDiscountId、userErrors

GraphQL 操作

discountNodes:query — 已针对 api_version 2025-01 验证

query DiscountAudit($after: String) { discountNodes(first: 250, after: $after) { edges { node { id discount { ... on DiscountCodeBasic { title status createdAt endsAt asyncUsageCount usageLimit codes(first: 5) { edges { node { id code } } } } ... on DiscountCodeBxgy { title status createdAt endsAt asyncUsageCount usageLimit } ... on DiscountCodeFreeShipping { title status createdAt endsAt asyncUsageCount usageLimit } } } } pageInfo { hasNextPage endCursor } } }

discountCodeDelete:mutation — 已针对 api_version 2025-01 验证

mutation DiscountCodeDelete($id: ID!) { discountCodeDelete(id: $id) { deletedCodeDiscountId userErrors { field message } } }

会话跟踪

每个阶段必须输出以下内容（强制要求）。

开始时输出：

╔══════════════════════════════════════════════╗ ║ SKILL: Discount Hygiene Cleanup ║ ║ 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>

如果 dry_run: true，则为每个变更步骤加 [DRY RUN] 前缀，且不执行该步骤。

完成时输出：

format: human（默认）时：

══════════════════════════════════════════════ OUTCOME SUMMARY Discounts scanned: <n> Expired: <n> Zero usage (> <n> days): <n> Total flagged: <n> Deleted: <n> Errors: <n> Output: discount_cleanup_<date>.csv ══════════════════════════════════════════════

format: json 时输出：

{ "skill": "discount-hygiene-cleanup", "store": "<domain>", "started_at": "<ISO8601>", "dry_run": true, "outcome": { "scanned": 0, "flagged_expired": 0, "flagged_zero_usage": 0, "deleted": 0, "errors": 0, "output_file": "discount_cleanup_<date>.csv" } }

输出格式

生成 CSV 文件 discount_cleanup_<YYYY-MM-DD>.csv，列包含： discount_id, title, status, created_at, ends_at, usage_count, usage_limit, flag_reason, action

错误处理

THROTTLED（API 速率超限）：等待 2 秒，最多重试 3 次
删除时出现 userErrors（折扣已被删除或正有活动订单使用）：记录错误，跳过并继续
无可标记的折扣（目录干净）：以 ✅ 无需清理退出

最佳实践

每季度运行一次——折扣码杂乱会随季节性活动迅速累积。
删除零使用折扣码前，请与邮件营销团队确认——它们可能正处于尚未启动的已计划活动中。
将 flag_zero_usage 的年龄阈值保持在 30 天以上，避免删除近期启动活动的折扣码。
自动/百分比折扣（非基于折扣码）不在此技能清理范围内，需单独管理。

技能介绍

discountNodes:query — 已针对 api_version 2025-01 验证

discountCodeDelete:mutation — 已针对 api_version 2025-01 验证