POS 集成¶
Gift Card Hero 会在 Shopify POS 中添加一个图块，让店内员工无需离开 POS 界面即可使用礼品卡工具。您可以在 Gift Card Hero 的 POS tools 中控制员工可以执行哪些操作。
没有使用 Shopify POS？ 如果您的店铺使用非 Shopify 收银系统 —— Square、Clover、Lightspeed、Zettle 等 —— 请改为参阅 第三方 POS 上的礼品卡（PWA）。
员工可以在 POS 中做什么¶
- 查询礼品卡余额 —— 输入或扫描代码，查看当前余额
- 登记实体礼品卡 —— 将印刷卡片的代码转换为带有余额的有效礼品卡
- 为礼品卡充值 —— 设置新余额，或增加、扣减一定金额，并可在购物车中同时添加付款
- 处理退款至礼品卡 —— 将退款金额作为店铺余额发放到新卡或现有卡上
- 查看客户的礼品卡 —— 查看与某客户关联的所有卡片，并为其充值
- 将卡片同步到您的门店网络 —— 适用于多店铺设置
设置¶
第 1 步 —— 将图块添加到 POS 主屏幕¶
- 打开 Shopify POS 应用
- 按下 Add tile 按钮
- 进入 Apps 菜单项
- 从列表中选择 Gift Card Hero
- 按下 POS UI Extension 按钮
- 按下 Done
Gift Hero 图块（"Manage gift cards and rewards"）现在会出现在 POS 主屏幕上。按下它即可打开 Gift Card Hero 工具。相同的步骤也显示在 Gift Card Hero 的 POS tools → Shopify POS 中，位于 How to Add POS Tools to Your POS App 方框内。
请使用 POS UI Extension，而不是 App link
Shopify 还提供一个 App link 图块。它已被弃用，不推荐使用。
第 2 步 —— 选择员工可以执行的操作¶
打开左侧导航中的 POS tools，停留在 Shopify POS 标签页。设置通过保存栏中的 Save 按钮保存。
| 设置 | 效果 |
|---|---|
| Disable balance reload functionality in Shopify POS app | 员工无法为卡片充值。Reload Gift Card 会显示 "Gift card reload is not allowed."。 |
| Disable gift card registration in Shopify POS app | 隐藏礼品卡登记功能，使员工无法在未付款的情况下创建礼品卡。Register Gift Card 会显示 "Gift card registration is not allowed."。 |
| Increase balance only after payment is completed | 只有在 Shopify POS 中完成付款后，充值才会生效。 |
| Default to 'Add payment to cart' on the reload screen | 在充值界面中预选 Add payment to cart，而不是 No payment required。 |
| Allow only redeeming gift cards in POS | 员工只能消费余额：充值和增加余额的功能都会被关闭。 |
| Available balance change actions | Both（默认）、Set final balance 或 Set amount（在 POS 中显示为 Add or deduct amount）—— 决定员工在充值界面中看到哪些调整方式。 |
当 Disable balance reload 被勾选时，付款选项不可用；Allow only redeeming 不能与其同时使用。
快速模式¶
勾选 Enable Quick Mode，即可跳过主菜单：打开图块后会直接进入 Reload Balance 的卡片列表。然后使用 Hide fields on Reload Balance screen 隐藏员工不需要的内容，包括 Adjustment method、Payment options、Internal note、Email notification 和 Transaction history。
POS 扩展功能¶
Gift Card Hero POS 扩展会向 Shopify POS 添加以下几个部分：
主页图块¶
Gift Hero 图块会打开 Gift Hero Tools，其中包含 Check Balance、Reload Gift Card 和 Register Gift Card。（开启快速模式后，它会改为打开充值卡片列表。）
查询余额¶
点击 Scan gift card QR code，或在 Search gift cards 中输入代码，然后点击 Search。结果会显示礼品卡（末尾几位字符）、其 Balance，以及（如适用）停用日期或到期日期。如果找不到该代码，系统会提供 Register this gift card 选项。
如果设备没有摄像头，或未授予摄像头权限，屏幕上会有相应提示，并建议使用硬件扫描器。
登记礼品卡¶
在收银台激活印刷的礼品卡。员工扫描卡片的二维码或输入其代码（至少 8 个字符），输入 Gift card value，然后点击 Register Gift Card。该代码会成为一张具有该余额的有效 Shopify 礼品卡；如果该代码已作为礼品卡存在，则会被拒绝。
登记时不会收取付款，因此员工需确保该卡的面值已经付清。若要对员工隐藏此选项，请在 POS tools 中勾选 Disable gift card registration in Shopify POS app。有关激活印刷卡片的其他方式，请参见实体礼品卡。
充值余额¶
在收银台为礼品卡增加资金。按代码搜索卡片，或将搜索框留空以列出卡片，然后点击该卡（已停用的卡无法打开）。充值界面会显示 Current balance，并包括：
- Adjustment method —— Set final balance，或 Add or deduct amount（然后选择 Add to balance 或 Deduct from balance）。
- New balance、Amount to add 或 Amount to deduct。
- No payment required 或 Add payment to cart —— 选择后会出现 Payment amount，并随增加的金额变化。
- 可选的 Internal note。
- Send email notification，用于通知客户 —— 当卡片关联了客户时可用。主题和内容已预先填写，且可以编辑；文字内容来自充值余额邮件。
- Apply changes。该卡的 Recent transactions 会列在下方。
订单退款¶
在订单详情界面中，员工点击 Refund to gift card。退款界面提供：
- Refund to existing gift card —— 客户的卡片（前三张），前提是订单有关联客户。
- Items to refund —— 为每个订单行项目选择数量。Refund amount 会随选择变化，并可编辑。
- 内部 Note，以及客户的邮箱 —— 如果订单没有邮箱，员工可以添加。
- 新卡的 No expiration 或 Add expiration date。
点击 Refund 按钮（上面显示金额）即可发放退款。之后 Gift Card Details 界面会显示该卡的面值和代码，并允许员工在需要时重新发行该卡。有关政策方面的内容，请参见将退款作为礼品卡。
客户礼品卡¶
当 POS 中打开了某位客户时，客户详情界面会有 Manage gift cards 按钮（也可在操作菜单中选择 View gift cards）。它会打开该客户的礼品卡，每张卡都显示其余额、交易历史以及 Reload balance 按钮。
将卡片同步到网络¶
对于多店铺网络中的店铺，订单详情和购后页面都提供 Sync gift card to network：扫描或输入礼品卡代码，然后点击 Sync to network，即可使该卡在网络中的所有店铺中可用。
接受礼品卡作为付款¶
礼品卡在结账时的兑换由 Shopify POS 原生处理 —— 无需 Gift Card Hero 的任何操作。当客户想用礼品卡付款时：
- 像平常一样将商品加入购物车
- 点击 Charge
- 选择 Gift Card 作为付款方式
- 扫描或输入代码
Shopify POS 会自动从余额中扣除。
如果您开启了兑换通知，根据通知对象的设置，持卡人（或购买者，或两者）也会收到通知，告知其消费了多少、剩余多少以及在哪个门店消费。
故障排除¶
POS 中没有出现 Gift Card Hero 图块¶
- 将 Shopify POS 应用更新到最新版本
- 打开图块选择器（Add tile → Apps），确认 Gift Card Hero 已列出，然后使用 POS UI Extension 重新添加
- 在 iPad 上：强制关闭并重新打开 POS 应用
POS 图块中出现 "Failed to load" 错误¶
POS 设备无法连接到 Gift Card Hero API。请检查： - 设备是否已连接到互联网？ - 是否有防火墙或内容过滤器阻止了出站连接？ - 尝试在 WiFi 与蜂窝网络之间切换，以排查网络问题
"Action not allowed"¶
该操作已在 POS tools → Shopify POS 中被关闭。如果员工应当能够使用该功能，请取消勾选对应的设置。
扫描时摄像头显示黑屏（iPad）¶
Gift Card Hero 扩展需要较新的 Shopify POS API 版本（2026-07 或更高）才能在 iPad 上显示摄像头。请将 Shopify POS 应用更新到最新版本，并重新打开图块。如果摄像头仍然是黑屏，请在 Search gift cards 中手动输入代码，或使用硬件扫描器。
扫描按钮不见了¶
设备没有摄像头，或尚未授予摄像头权限。请在设备设置中为 Shopify POS 允许摄像头权限，或使用硬件扫描器，或手动输入代码。
余额查询显示的金额有误¶
显示的余额是从 Shopify 实时获取的。如果看起来过时，请检查设备的网络连接并重试。
礼品卡邮件/余额页面中的二维码无法在 POS 中扫描¶
症状： - 每封礼品卡邮件中的二维码看起来都相同 - 在 Shopify POS 中扫描该二维码没有任何反应，或返回 "not found" - 添加到 Apple Wallet 中的二维码可以正常扫描
原因：礼品卡余额页面（/gift_cards/{id}/{token}）缺少用于渲染每张卡专属二维码的动态 QrCode Liquid 对象。当该对象未被提供时，Gift Card Hero 会回退为静态占位图片，因此每封邮件都会带有相同的、无法扫描的代码。
解决方法：请联系 Gift Card Hero 支持，并提供受影响店铺的域名 —— 我们会在我们这边修补渲染逻辑，以正确生成每张卡专属的二维码。修复之后，邮件和余额页面都会显示可在 POS 中扫描的唯一二维码。