用途
该技能用于以编程方式向客户发放 Shopify 原生礼品卡，可作为延迟发货的善意补偿、替代现金退款的店铺余额，或忠诚度奖励。它使用 Shopify 内置的礼品卡系统，无需第三方应用。此处发放的礼品卡与手动创建的礼品卡一样，可在结账时正常兑换。注意：giftCardCreate 在所有 Shopify 套餐中均可用，但可能要求店铺在设置中启用礼品卡功能。
前置条件
- 认证命令：shopify auth login --store <domain>
- API 权限范围：read_customers、write_gift_cards
- 必须在 Shopify 后台 → 设置 → 礼品卡中启用礼品卡功能
参数
- store（字符串，必填）：店铺域名，例如 mystore.myshopify.com
- format（字符串，可选，默认 human）：输出格式，human 或 json
- dry_run（布尔值，可选，默认 false）：预览操作而不执行变更
- customer_email（字符串，必填*）：用于查找并关联礼品卡的客户邮箱
- customer_id（字符串，必填*）：客户 GID（作为邮箱的替代方式）
- amount（浮点数，必填）：礼品卡价值，使用店铺默认货币
- reason（字符串，可选）：记录在礼品卡上的内部备注，例如“Goodwill: delayed shipment #1042”
- expires_on（字符串，可选）：ISO 8601 格式的到期日期，例如 2026-12-31；若省略则礼品卡不过期
- tag_customer（字符串，可选）：可选添加到客户记录的标签，例如 goodwill-issued
- customer_email 与 customer_id 必须提供其中之一。
安全提示
⚠️ 第 2 步执行 giftCardCreate 会针对你的店铺发放真实货币价值。礼品卡创建后无法删除，只能被禁用。请先以 dry_run: true 运行，确认客户、金额和到期日后再提交。请仔细核对金额——发放的价值可立即在结账时兑换。
工作流程步骤
-
OPERATION: customer — 查询
- 输入：通过 customer_email（使用 customers 搜索）或直接通过 customer_id 查找
- 预期输出：客户 id、firstName、lastName、email；在发放前确认客户存在
-
OPERATION: giftCardCreate — 变更
- 输入：input.initialValue、input.customerId、input.expiresOn（可选）、input.note（reason）
- 预期输出：giftCard.id、giftCard.code、giftCard.balance、giftCard.expiresOn、userErrors
GraphQL 操作
customer:query — 已针对 api_version 2025-01 验证
query CustomerByEmail($query: String!) { customers(first: 1, query: $query) { edges { node { id firstName lastName defaultEmailAddress { emailAddress } tags } } } }
giftCardCreate:mutation — 已针对 api_version 2025-01 验证
mutation GiftCardCreate($input: GiftCardCreateInput!) { giftCardCreate(input: $input) { giftCard { id code balance { amount currencyCode } expiresOn note customer { id } } userErrors { field message } } }
会话跟踪
Claude 必须在每个阶段输出以下内容。这是强制要求。
开始时输出：
╔══════════════════════════════════════════════╗ ║ SKILL: gift-card-issuance ║ ║ 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 Customer: <name> (<email>) Gift card code: <code> Amount: <amount> <currency> Expires: <date or "Does not expire"> Errors: 0 Output: none ══════════════════════════════════════════════
对于 format: json，输出：
{ "skill": "gift-card-issuance", "store": "<domain>", "started_at": "<ISO8601>", "completed_at": "<ISO8601>", "dry_run": false, "steps": [ { "step": 1, "operation": "CustomerByEmail", "type": "query", "params_summary": "email <email>", "result_summary": "customer <id>", "skipped": false }, { "step": 2, "operation": "GiftCardCreate", "type": "mutation", "params_summary": "amount <amount>, customer <id>", "result_summary": "gift card <code>", "skipped": false } ], "outcome": { "customer_id": "<id>", "customer_email": "<email>", "gift_card_id": "<id>", "gift_card_code": "<code>", "amount": "<amount>", "currency": "<currency>", "expires_on": "<date or null>", "errors": 0, "output_file": null } }
输出格式
不使用 CSV。会话摘要会内联报告礼品卡代码和金额。客服人员复制该代码分享给客户。
礼品卡已发放： Customer: Jane Smith (jane@example.com) Code: ABCD-EFGH-IJKL-MNOP Value: $25.00 USD Expires: 2026-12-31 (or "Does not expire") Note: Goodwill: delayed shipment #1042
错误处理
- 客户未找到：邮箱不匹配任何客户。恢复方式：核实邮箱；访客结账客户可能没有客户记录。
- giftCardCreate 返回 userErrors：金额无效（≤ 0）或缺少必填字段。恢复方式：确认金额为正数。
- 礼品卡未启用：店铺设置不允许礼品卡。恢复方式：在 Shopify 后台 → 设置 → 礼品卡中启用。
- 缺少 write_gift_cards 权限范围：认证时未包含此范围。恢复方式：使用 write_gift_cards 范围重新运行 shopify store auth。
最佳实践
- 始终先运行 dry_run: true，确认客户查找成功且金额正确后再发放。
- 始终包含 reason 备注——它会出现在礼品卡记录中，有助于团队日后审计发放情况。
- 设置 tag_customer: goodwill-issued 以跟踪哪些客户收到了善意礼品卡——可结合 loyalty-segment-export 监控其后续购买行为。
- 对促销礼品卡（例如节日活动）使用 expires_on 以制造紧迫感；对善意发放则省略该参数，让客户感到此举真诚。
- 对于批量发放（例如影响 100 位客户的服务中断），使用 format: json 循环遍历客户列表，以捕获每张礼品卡代码用于记录。