gift-card-issuance

用途

该技能用于向 Shopify 客户以编程方式发放 Shopify 原生礼品卡——可以作为延迟发货的善意补偿、替代现金退款的商店余额，或忠诚度奖励。它使用 Shopify 内置的礼品卡系统，无需第三方应用。此处发放的礼品卡与手动创建的礼品卡一样，可在结账时兑换。注意：giftCardCreate 在所有 Shopify 套餐中均可用，但可能需要商店在设置中启用礼品卡。该技能替代了在 Shopify 后台手动创建礼品卡，以及退货/忠诚度应用中的商店余额功能。

前置条件

shopify auth login --store <domain>
API 权限范围：read_customers、write_gift_cards
必须在 Shopify 后台 → 设置 → 礼品卡中启用礼品卡

参数

参数	类型	必填	默认值	说明
store	string	是	—	商店域名（例如 mystore.myshopify.com）
format	string	否	human	输出格式：human 或 json
dry_run	bool	否	false	预览操作而不执行变更
customer_email	string	是*	—	用于查找并关联礼品卡的客户邮箱
customer_id	string	是*	—	客户 GID（作为邮箱的替代方式）
amount	float	是	—	以商店默认货币计的礼品卡金额
reason	string	否	—	记录在礼品卡上的内部备注（例如 "Goodwill: delayed shipment #1042"）
expires_on	string	否	—	ISO 8601 格式的到期日期（例如 2026-12-31）；若省略，则礼品卡永不过期
tag_customer	string	否	—	可选的客户记录标签（例如 goodwill-issued）

* customer_email 与 customer_id 二者之一为必填。

安全性

⚠️ 第 2 步会执行 giftCardCreate，这会针对你的商店发放真实货币价值。礼品卡一旦创建便无法删除——只能被禁用。请使用 dry_run: true 运行，以在提交前确认客户、金额和有效期。请仔细核对金额——所发放的价值会立即可在结账时兑换。

工作流程步骤

操作：customer — 查询输入：按 customer_email 查找（使用 customers 搜索）或直接按 customer_id 查找预期输出：客户 id、firstName、lastName、email；在发放前确认客户存在

操作：giftCardCreate — 变更输入：input.initialValue、input.customerId、input.expiresOn（可选）、input.note（reason）预期输出：giftCard.id、giftCard.code、giftCard.balance、giftCard.expiresOn、userErrors

GraphQL 操作

# customer:query — validated against api_version 2025-01
query CustomerByEmail($query: String!) {
  customers(first: 1, query: $query) {
    edges {
      node {
        id
        firstName
        lastName
        defaultEmailAddress {
          emailAddress
        }
        tags
      }
    }
  }
}

# giftCardCreate:mutation — validated against 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。会话摘要会内联报告礼品卡代码和金额。支持人员复制该代码以分享给客户。

Gift card issued:
  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

错误处理

错误	原因	恢复方式
Customer not found	邮箱未匹配到任何客户	核实邮箱；访客结账客户可能没有客户记录
giftCardCreate 的 userErrors	金额无效（≤ 0）或缺少必填字段	核实金额为正数
Gift cards not enabled	商店设置不允许礼品卡	在 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 遍历客户列表以捕获每个礼品卡代码供记录。