shopify-admin-gift-card-balance-report

用途

该技能查询所有启用和部分兑换的礼品卡，报告未兑换余额所对应的礼品卡总负债。适用于资产负债表报告、递延收入核算，以及在礼品卡到期前审计未使用的礼品卡。该技能为只读操作，不执行任何变更。

前置条件

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

参数

参数	类型	必填	默认值	说明
store	string	是	—	店铺域名（例如 mystore.myshopify.com）
status	string	否	enabled	按状态筛选：enabled、disabled 或 all
expiring_within_days	integer	否	30	标记在指定天数内即将过期的礼品卡
format	string	否	human	输出格式：human 或 json

安全性

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

工作流程步骤

操作：giftCards — 查询
- 输入：query: "status:<status>"、first: 250、分页游标
- 预期输出：所有匹配的礼品卡，包含 balance、initialValue、expiresOn、lastCharacter、usedOn；分页直到 hasNextPage: false
标记在 expiring_within_days 内即将过期的礼品卡
汇总：未兑换余额总额（负债）、按状态计数、已发行初始价值总额

GraphQL 操作

# giftCards:query — validated against api_version 2025-01
query GiftCardBalances($query: String, $after: String) {
  giftCards(first: 250, after: $after, query: $query) {
    edges {
      node {
        id
        balance {
          amount
          currencyCode
        }
        initialValue {
          amount
          currencyCode
        }
        enabled
        expiresOn
        createdAt
        lastCharacters
        customer {
          id
          displayName
          defaultEmailAddress {
            emailAddress
          }
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

会话跟踪

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

启动时输出：

╔══════════════════════════════════════════════╗
║  SKILL: Gift Card Balance 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（默认）时：

══════════════════════════════════════════════
GIFT CARD BALANCE REPORT
  Active gift cards:          <n>
  Total outstanding balance:  $<amount>  (liability)
  Total initial value issued: $<amount>
  Redeemed to date:           $<amount>
  Expiring in <n> days:       <n> cards  ($<amount>)
  Output: gift_card_balances_<date>.csv
══════════════════════════════════════════════

format 为 json 时输出：

{
  "skill": "gift-card-balance-report",
  "store": "<domain>",
  "active_count": 0,
  "total_outstanding_balance": 0,
  "total_initial_value": 0,
  "currency": "USD",
  "expiring_soon_count": 0,
  "expiring_soon_value": 0,
  "output_file": "gift_card_balances_<date>.csv"
}

输出格式

生成 CSV 文件 gift_card_balances_<YYYY-MM-DD>.csv，包含列：

gift_card_id, last_characters, status, initial_value, balance, currency, created_at, expires_on, customer_email, expiring_soon

错误处理

错误	原因	恢复方式
THROTTLED	API 速率限制超出	等待 2 秒，最多重试 3 次
No gift cards	店铺未发行任何礼品卡	以 0 总负债退出
Gift card with no customer	发行时无客户账户	显示为 "Anonymous"

最佳实践

未兑换余额总额是资产负债表上的递延收入负债，应纳入每月财务结账。
在 expiring_within_days 内即将过期的礼品卡代表即将减少的负债，无需采取行动，但有助于预测。
对于高价值未兑换余额，可与 customer-spend-tier-tagger 交叉比对，针对高余额持卡人开展提醒活动。
与 gift-card-issuance（转化优化技能）配合使用，跟踪一段时间内发行与兑换的礼品卡。