shopify-admin-gift-card-liability-report

用途

本技能计算商店的礼品卡总负债——即所有未兑换礼品卡余额之和，代表未来交付商品的义务。它按发卡月份（issue-month cohort）和剩余余额区间（remaining-balance band）拆分负债，便于财务衡量负债规模、账龄并预测失效（breakage）。它是 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
balance_bands	array	否	[10, 50, 100, 250, 500]	余额区间的上边界（以商店货币计），用于分布表
stale_days	integer	否	365	超过此天数未变动的卡被标记为失效候选
as_of	string	否	今天（UTC）	报告中“as of”快照标签的 ISO 日期
format	string	否	human	输出格式：human 或 json

安全说明

本技能为只读，不执行任何变更。产出的金额是会计意义上的递延收入负债；在登记日记账分录前请与会计师确认。

负债模型

对每张余额大于 0 的已启用礼品卡：

未兑换余额 = balance.amount 之和（即负债）
发卡 cohort = createdAt 的年-月
余额区间 = 第一个大于等于剩余余额的区间边界，超过最大边界则归为 >max
失效候选 = 余额大于 0 且（updatedAt 早于 stale_days 之前，或 expiresOn 在未来 30 天内）

聚合项：

总未兑换（整体 + 每个 cohort + 每个区间）
每个 cohort 和每个区间的卡数量
自发行以来的加权平均天数
失效候选总额——对于允许确认失效的司法管辖区，可用于 ASC 606 / IFRS 15 下的收入确认

工作流程

OPERATION: giftCards — 查询
- 输入：query: "status:<status> balance:>0"，first: 250，选择 id、balance、initialValue、createdAt、updatedAt、expiresOn、enabled、lastCharacters、分页游标
- 预期输出：所有余额为正的礼品卡；分页直到 hasNextPage: false
对每张卡计算发卡 cohort、余额区间和失效标记
聚合总额：整体负债、按 cohort 表、按区间表、失效候选小计
计算至今已兑换额 = Σ(initialValue - balance)，用于上下文

GraphQL 操作

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

会话跟踪

Claude 必须在每个阶段输出以下内容，这是强制要求。

开始时输出：

╔══════════════════════════════════════════════╗
║  SKILL: Gift Card Liability Report           ║
║  Store: <store domain>                       ║
║  As of: <YYYY-MM-DD>                         ║
║  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 LIABILITY  (as of <date>)
  Active cards w/ balance:   <n>
  Total outstanding:         $<amount>
  Initial value issued:      $<amount>
  Redeemed to date:          $<amount>  (<pct>%)
  Breakage candidates:       <n>  ($<amount>)

  By issue cohort (YYYY-MM):
    2024-12  Cards: <n>  Liability: $<n>
    2025-01  Cards: <n>  Liability: $<n>

  By balance band:
    ≤ $10     Cards: <n>  Liability: $<n>
    ≤ $50     Cards: <n>  Liability: $<n>
    ≤ $100    Cards: <n>  Liability: $<n>
    > $500    Cards: <n>  Liability: $<n>

  Output: gift_card_liability_<date>.csv
══════════════════════════════════════════════

format 为 json 时输出：

{
  "skill": "gift-card-liability-report",
  "store": "<domain>",
  "as_of": "<YYYY-MM-DD>",
  "active_with_balance": 0,
  "total_outstanding": 0,
  "initial_value_issued": 0,
  "redeemed_to_date": 0,
  "redemption_rate_pct": 0,
  "breakage_candidates_count": 0,
  "breakage_candidates_value": 0,
  "currency": "USD",
  "by_cohort": [],
  "by_band": [],
  "output_file": "gift_card_liability_<date>.csv"
}

输出格式

CSV 文件 gift_card_liability_<YYYY-MM-DD>.csv，列包括： gift_card_id, last_characters, initial_value, balance, redeemed, currency, created_at, issue_cohort, balance_band, updated_at, expires_on, breakage_candidate, customer_email

错误处理

错误	原因	恢复方式
THROTTLED	超出 API 速率限制	等待 2 秒，最多重试 3 次
无余额为正的礼品卡	商店未发行过，或全部已兑换	以 $0 负债退出
多币种卡	卡以不同展示货币发行	按货币代码分组汇总；不要跨货币相加
expiresOn 为 null 的卡	无到期策略	视为不过期；不纳入基于到期的失效

最佳实践

在每个会计期间的最后一天运行，使数字与资产负债表结账对齐。
总未兑换金额是递延收入负债——应记入会计系统，不要把已发行的礼品卡当作收入。
失效政策因司法管辖区而异；在将失效候选确认为收入前请咨询会计师。此处的 stale_days 和 expiresOn 标记是该政策的输入，而非替代。
逐月跟踪兑换率趋势——兑换率下降可能表明客户体验问题（收礼人找不到或忘记他们的卡）。
与 gift-card-issuance 配合监控流量：负债应随发行增加，随兑换 + 失效减少。