Gift Card Hero REST API¶
REST API 让您可以从外部系统以编程方式管理礼品卡——包括 CRM、分析仪表板、忠诚度平台、履约服务等。
基础 URL¶
所有 API 请求均使用以下基础 URL：
https://gifthero.syncu.be/api/external
身份验证¶
每个请求都必须在 Authorization 标头中包含 Bearer 令牌：
Authorization: Bearer YOUR_API_TOKEN
要获取您的 API 令牌，请在左侧导航中前往 For developers，勾选 Enable REST API 并保存。点击 Send me access token——令牌将发送至页面上显示的店铺联系邮箱。
在您替换或撤销令牌之前，令牌不会过期。请像对待密码一样保管：将其存放在集成的机密设置中，切勿将其粘贴到聊天、工单或共享文档中。
管理您的 API 令牌¶
一次只能有一个令牌。 您的店铺只有一个 API 令牌。每个调用 API 的系统——POS、CRM、合作伙伴的服务——都使用同一个令牌。
发送新令牌会替换旧令牌。 每次点击 Send me access token 都会签发一个新令牌，之前的令牌会立即失效。请立即用新令牌更新每个集成。如果您只是需要再次查看令牌，请找到之前的邮件，而不要发送新令牌。
撤销令牌。 如果令牌可能已泄露，或持有该令牌的合作伙伴已不再与您合作，请在 For developers 页面点击 Revoke access token 并确认。令牌会立即失效，且不会签发新令牌。准备就绪后，点击 Send me access token 签发新令牌。
关闭 REST API。 将 Enable REST API 关闭并保存，同样会撤销令牌。重新开启 API 后，请给自己发送一个新令牌。
您的集成会看到的内容。 使用已被替换或撤销的令牌的请求将返回 401：
{
"error": {
"statusCode": 401,
"name": "UnauthorizedError",
"message": "Error verifying token : The token has been revoked or replaced."
}
}
解决方法始终相同：在 Authorization 标头中使用当前令牌。
在引入令牌 ID 之前签发的令牌，会一直有效，直到您首次发送新令牌或撤销该令牌为止。
其他身份验证错误：
| 状态 | 含义 |
|---|---|
401 |
Authorization 标头缺失或不是 Bearer 类型，或令牌无效 |
402 |
店铺没有有效的 Gift Card Hero 套餐 |
端点¶
列出礼品卡¶
GET /gift-cards
参数：
| 参数 | 类型 | 说明 |
|---|---|---|
status |
string | 按礼品卡状态筛选 |
limit |
integer | 最大结果数（最多 250） |
since_id |
string | 返回该礼品卡 ID 之后的结果 |
fields |
string | 以逗号分隔的、要包含的字段列表 |
该请求会转发给 Shopify 的礼品卡列表，因此适用 Shopify 自身对该列表的参数。响应中的每张卡都带有 recipient 对象（id、email、name）或 null。当 Gift Card Hero 有完整代码记录时，响应中会包含 code 字段（参见重要说明）。
HEAD /gift-cards 请求返回 200，且无响应体。某些 HTTP 客户端会将其用作预检。
列出含交易记录的礼品卡¶
GET /gift-cards/transactions
按最新优先返回礼品卡，每张卡最多附带其 50 条最近交易。支持基于游标的分页。
分页：
| 参数 | 类型 | 说明 |
|---|---|---|
limit |
integer | 每页礼品卡数（默认 50） |
page_info |
string | 下一页结果的游标 |
筛选条件：
| 筛选条件 | 类型 | 说明 |
|---|---|---|
query |
string | 搜索查询，使用 Shopify 礼品卡搜索语法 |
balance_status |
string | 可选值：full、partial、empty、full_or_partial |
created_at |
string | 按创建日期筛选 |
expires_on |
string | 按到期日期筛选 |
source |
string | 可选值：manual、purchased、api_client |
status |
string | 可选值：disabled、enabled、expired、expiring |
initial_value |
string | 按初始金额筛选 |
id |
string | 按礼品卡 ID 筛选 |
组合使用时，所有筛选条件之间为 AND 逻辑。
响应：
每张礼品卡包含 id、balance、currency、initial_value、created_at、updated_at、disabled_at、customer_id、recipient、note、expires_on、template_suffix、last_characters、order_id、transactions 和 issued_by。响应不包含礼品卡代码。每条交易包含 id、amount（借记为负数）、processed_at、note、pos_user 和 pos_order_name。
交易 ID：
transactions[].id 是礼品卡交易的数字型 Shopify ID——即 gid://shopify/GiftCardDebitTransaction/… 或 gid://shopify/GiftCardCreditTransaction/… GID 末尾的数字。早期版本的 API 在此处返回 null。
POS 字段：
通过 Gift Card Hero POS 发行或兑换的礼品卡会记录执行该操作的收银员。以下字段会添加到标准响应中：
| 字段 | 类型 | 说明 |
|---|---|---|
transactions[].pos_user |
object 或 null | 在 POS 上进行的借记为 { "username": "woodgrove", "name": "Woodgrove" }；否则为 null |
transactions[].pos_order_name |
string 或 null | 该笔借记在 POS 上输入的订单名称（如有）；否则为 null |
issued_by |
object 或 null | 在 POS 上发行的礼品卡为 { "username", "name", "issued_at" }；否则为 null |
POS 活动日志不保存 Shopify 交易 ID，因此借记会通过卡号、金额和时间与 POS 兑换记录进行匹配（兑换必须在交易前几秒至交易后一分钟内记录）。线上支付、在 Shopify 后台所做的更改，以及没有匹配 POS 记录的借记，都将返回 null。如果 POS 用户已被删除，name 为 null。
获取单张礼品卡¶
GET /gift-cards/{gift_card_id}
通过 ID 返回单张礼品卡的详细信息，包括其 recipient，以及（当 Gift Card Hero 有记录时）其 code。
创建礼品卡¶
POST /gift-cards
请求体：
{
"note": "Loyalty reward",
"initial_value": "50.00",
"code": "ABCD-EFGH-IJKL-MNOP",
"template_suffix": "custom"
}
| 字段 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
note |
string | 否 | 礼品卡的内部备注 |
initial_value |
string | 是 | 初始余额 |
code |
string | 否 | 自定义礼品卡代码（必须唯一；如省略则自动生成） |
template_suffix |
string | 否 | Shopify 模板后缀 |
customer_id |
integer | 否 | 拥有该卡的 Shopify 客户 |
email |
string | 否 | 客户邮箱，在未发送 customer_id 时使用。Gift Card Hero 会查找该客户，或创建一个带有标签 gifthero:import 的客户 |
请求体会转发给 Shopify 的礼品卡端点，该端点还接受 expires_on 等其他字段。响应为 Shopify 的礼品卡对象，包含完整的 code。
重要： 如果您需要礼品卡代码，请保存创建响应中的完整代码。之后的响应只有在 Gift Card Hero 有记录时才会包含完整的
code；否则仅返回后 4 位（last_characters）。
更新礼品卡余额¶
PUT /gift-cards/{gift_card_id}/balance
请求体：
{
"balance": "100.00"
}
将礼品卡余额设置为指定值。带有正负号的值（例如 "+25.00" 或 "-10.00"）将作为对当前余额的调整应用。如果余额没有变化，则返回当前余额，且不记录任何内容。当店铺开启 Increase limit 时，充值金额可以超过 Shopify 礼品卡的标准上限。
这是余额更正：不会向客户发送任何通知，也不记录分店信息。当客户在收银台消费礼品卡时，请改用兑换礼品卡。
兑换礼品卡¶
POST /gift-cards/{gift_card_id}/redeem
从第三方 POS 或收银应用中对礼品卡进行借记（兑换），不经过 Shopify 结账。持卡人会收到您店铺的兑换通知（电子邮件或短信），其中包含分店名称——若兑换通知设置中的 Who gets notified 如此指定，则改为通知购买者，或两者都通知——并且该兑换会连同其分店显示在 Gift Card Hero 报告中。请使用此方法，而不要直接调用 Shopify 的 giftCardDebit——直接借记不会记录分店，也不会发送通知。
兑换与更新余额的区别： 如果只想将余额设为某个值而不通知任何人，请使用 更新礼品卡余额。当客户消费礼品卡，且您希望记录通知和分店时，请使用兑换。
请求体：
{
"amount": "1500.00",
"branch": "Westgate",
"reference": "pos-app:7f3c2b9e-0d1a-4c55-9b7e-2f8a6c1d3e4f",
"note": "Table 12"
}
| 字段 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
amount |
string | 是 | 要兑换的金额。必须大于 0，且不超过礼品卡余额，以卡的货币计，最多 2 位小数 |
branch |
string | 是 | 分店或地点名称。显示在兑换邮件和短信中（当兑换通知中开启 Include the store location 时），以及报告中 |
reference |
string | 是 | 您为本次兑换提供的唯一 ID，最多 255 个字符。参见重试与重复 |
note |
string | 否 | 写入 Shopify 中的礼品卡交易。Gift Card Hero 会在备注后附加 [ref:<reference>]，以便您在 Shopify 后台将每笔 API 兑换与其 reference 对应起来 |
响应（200）：
{
"id": 661944893757,
"last_characters": "7nsf",
"amount": "1500.00",
"currency": "KES",
"balance_before": "5090.00",
"balance": "3590.00",
"branch": "Westgate",
"reference": "pos-app:7f3c2b9e-0d1a-4c55-9b7e-2f8a6c1d3e4f",
"processed_at": "2026-10-12T10:30:00Z",
"notification": "queued",
"duplicate": false
}
| 字段 | 说明 |
|---|---|
notification |
queued —— 兑换通知已交由您店铺的兑换通知设置处理，该设置决定是否发送（每次兑换都发送，或仅在卡被用完时发送）。disabled —— 您店铺已关闭兑换通知 |
duplicate |
当该 reference 已被处理过时为 true，此时响应为原始结果 |
错误：
错误使用常规格式：{"error": {"statusCode": 422, "name": "...", "message": "..."}}。
| 状态 | 含义 | 处理方法 |
|---|---|---|
400 |
amount、branch 或 reference 缺失或无效 |
修正请求体 |
401 |
令牌缺失、无效、已撤销或已被较新的令牌替换 | 检查 Authorization 标头。如果令牌已被撤销或替换，请申请新令牌 |
403 |
应用在您的店铺中缺少某项访问权限 | 店铺所有者需在 Shopify 后台批准应用更新后的权限 |
404 |
未找到礼品卡 | 检查礼品卡 ID |
409 |
该 reference 已用于另一张卡或另一金额，或使用该 reference 的请求仍在处理中 |
如为新的兑换，请使用新的 reference。如果请求仍在处理中，请等待几秒后使用相同的 reference 重试 |
422 |
卡已停用或已过期，或金额超过余额。message 会说明具体原因。余额保持不变 |
修正原因。该 reference 未被占用，因此请使用相同的 reference 重试 |
429 |
Shopify 正在对您的店铺进行速率限制 | 退避后使用相同的 reference 重试 |
500 |
无法向 Shopify 确认结果 | 使用相同的 reference 重试：卡不会被重复扣款 |
失败的请求（404 或 422）不会占用 reference。
重试与重复¶
每次兑换生成一个 reference，且仅在重试同一次兑换时复用。如果请求超时或因网络失败，请使用相同的 reference 重试。这总是安全的：卡不会被重复扣款，并且您会收到原始结果，其中 "duplicate": true。
更新礼品卡¶
PUT /gift-cards/{gift_card_id}
只能更新以下字段：
| 字段 | 类型 | 说明 |
|---|---|---|
expires_on |
string | 到期日期 |
note |
string | 内部备注 |
template_suffix |
string | Shopify 模板后缀 |
customer_id |
integer | 拥有该卡的 Shopify 客户。与创建礼品卡时一样，您也可以改为发送 email |
当 Gift Card Hero 有记录时，响应中包含 code。
禁用礼品卡¶
POST /gift-cards/{gift_card_id}/disable
永久禁用该礼品卡。此操作无法撤销。返回已禁用的礼品卡。
搜索礼品卡¶
GET /gift-cards/search
参数：
| 参数 | 类型 | 说明 |
|---|---|---|
order |
string | 排序方式 |
query |
string | 搜索查询，例如 last_characters:mnop。使用 recipient:name@example.com 查找发送给某收件人的卡 |
limit |
integer | 最大结果数 |
fields |
string | 以逗号分隔的、要包含的字段列表 |
可索引字段（可用于搜索查询）：
created_at、updated_at、disabled_at、balance、initial_value、amount_spent、last_characters
将礼品卡代码分配到订单¶
POST /gift-cards/assign-to-order
将您自己的礼品卡代码分配给 Shopify 订单，适用于在应用外生成代码的店铺。仅当 Regular products as gift cards 设置中开启 Skip gift codes generation 时有效；否则返回 400。如果 orderId 不是数字，或某个代码已存在于您的店铺中，也返回 400；如果找不到订单，则返回 404。
同时支持单个和多个代码分配。
单个代码：
{
"orderId": "1234567890",
"giftCode": "ABCD-EFGH-IJKL-MNOP"
}
多个代码：
{
"orderId": "1234567890",
"giftCodes": [
{ "lineItemId": "111", "code": "ABCD-EFGH-IJKL-MNOP" },
{ "lineItemId": "222", "code": "QRST-UVWX-YZ12-3456" }
]
}
响应：
{
"scheduled": true
}
当订单没有需要处理的礼品卡时，scheduled 为 false。
分页¶
交易端点使用基于游标的分页。响应包含一个 Link 标头，其中带有下一页的游标：
Link: <https://gifthero.syncu.be/api/external/gift-cards/transactions?page_info=CURSOR>; rel="next"
最后一页不包含该标头。请从 Link 标头中解析出 page_info 的值，并在下一次请求中将其作为查询参数传递，同时保持相同的筛选条件。下一页的 URL 中已包含这些筛选条件。
重要说明¶
- 代码唯一性 —— 使用自定义代码创建礼品卡时，每个代码必须唯一。如果提交了重复的代码，API 会返回错误。
- 代码可见性 —— 创建响应包含完整代码。在之后的响应中，只有当 Gift Card Hero 有该卡的完整代码记录时（包括它生成的卡，以及您分配的代码），才会出现
code字段。否则仅返回后 4 位（last_characters）。交易端点从不返回代码。 - 兑换重试 —— 兑换礼品卡时，请始终发送唯一的
reference，并在超时后使用相同的reference重试。参见重试与重复。 - 速率限制 —— 请求会转发给 Shopify，因此适用您店铺的 Shopify 限制。如果收到
429响应，请退避后重试。 - Postman 集合 —— 涵盖礼品卡端点，但不包括
/gift-cards/transactions和/gift-cards/assign-to-order。
Postman 集合¶
下载 Postman 集合以便快速探索 API：