用途:查询所有有效及部分兑付的礼品卡,汇总未兑付余额(礼品卡负债),用于资产负债表报告、递延收入核算,以及在礼品卡到期前审计未使用余额。该技能为只读操作,不执行任何变更。
前置条件:已认证的 Shopify CLI 会话,命令为 shopify store auth --store <domain> --scopes read_gift_cards;API 权限范围为 read_gift_cards。
参数:store(字符串,必填,店铺域名,如 mystore.myshopify.com);status(字符串,可选,默认 enabled,可选 enabled、disabled 或 all);expiring_within_days(整数,可选,默认 30,标记在此天数内到期的礼品卡);format(字符串,可选,默认 human,可选 human 或 json)。
主要能力:通过 giftCards 查询分页获取礼品卡,包含 balance、initialValue、expiresOn、lastCharacters、usedOn 等字段;标记即将到期的卡;汇总未兑付总余额、按状态计数、已发行初始总值。输出 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。
使用方式:运行后按阶段输出会话信息与每步结果,完成后按 human 或 json 格式输出汇总。错误处理包括 THROTTLED 时等待 2 秒重试最多 3 次;无礼品卡时以 0 负债退出;无客户账户的礼品卡显示为 Anonymous。
适用场景:月度财务结账、递延收入负债跟踪、到期前审计、预测即将减少的负债。
限制:仅只读,不修改数据;需具备 read_gift_cards 权限;具体定价、平台支持范围等资料暂未提供。