查询礼品卡列表

GET 
/openapi/2025-06/gift_cards

分页返回符合过滤条件的礼品卡列表。

请求

Query参数

cursor string

分页游标

page_size int32

每页记录数，默认为 10

ids string[]

用于筛选的礼品卡 ID 列表。 示例：?ids=GC1001&ids=GC1002

created_at_min string

筛选在该时间及之后创建的礼品卡（如 2018-11-02T12:30:10Z）

created_at_max string

筛选在该时间及之前创建的礼品卡（如 2018-11-02T12:30:10Z）

updated_at_min string

筛选在该时间及之后最后更新的礼品卡（如 2018-11-02T12:30:10Z）

updated_at_max string

筛选在该时间及之前最后更新的礼品卡（如 2018-11-02T12:30:10Z）

initial_value_min float

筛选初始面值大于或等于该金额的礼品卡

initial_value_max float

筛选初始面值小于或等于该金额的礼品卡

status string
礼品卡状态：
• enable: 启用，礼品卡可正常使用
• disable: 禁用，礼品卡不可用
balance_status string

按礼品卡余额状态筛选

keyword string

用于搜索礼品卡的关键词（如匹配礼品卡码或备注）

sort_by string

用于排序的字段（如 created_at、updated_at）

sort_direction string
排序方向：
• asc: 升序
• desc: 降序

响应

200

OK

application/json

数据结构

数据结构

codestring

错误码

messagestring

错误信息

data object

gift_cards object[]

礼品卡列表

Array [

idstring

礼品卡 ID

last_charactersstring

礼品卡码的后四位

balancestring

礼品卡当前余额

initial_valuestring

礼品卡的初始面值

notestring

附加在礼品卡上的备注

expires_onstring

礼品卡到期时间（如 2018-11-02T12:30:10Z）

disabled_atstring

礼品卡被禁用的时间（如 2018-11-02T12:30:10Z）

enabledboolean

礼品卡当前是否已启用

created_atstring

礼品卡创建时间（如 2018-11-02T12:30:10Z）

updated_atstring

礼品卡最后更新时间（如 2018-11-02T12:30:10Z）

statusstring

礼品卡状态：

• enable: 启用，礼品卡可正常使用
• disable: 禁用，礼品卡不可用

currencystring

礼品卡面值所使用的货币

line_item_idstring

与礼品卡关联的商品行项目 ID

order_idstring

与礼品卡关联的订单 ID

user_idstring

礼品卡创建者或所有者的用户 ID

template_suffixstring

用于在线渲染礼品卡的模板后缀

customer_idstring

与礼品卡关联的顾客 ID

codestring

礼品卡码，由字母数字字符组成（最少 8 个字符，最多 20 个字符）

]

cursorstring

分页游标

has_moreboolean

是否有更多记录

示例

{
  "code": "string",
  "message": "string",
  "data": {
    "gift_cards": [
      {
        "id": "string",
        "last_characters": "string",
        "balance": "string",
        "initial_value": "string",
        "note": "string",
        "expires_on": "string",
        "disabled_at": "string",
        "enabled": true,
        "created_at": "string",
        "updated_at": "string",
        "status": "string",
        "currency": "string",
        "line_item_id": "string",
        "order_id": "string",
        "user_id": "string",
        "template_suffix": "string",
        "customer_id": "string",
        "code": "string"
      }
    ],
    "cursor": "string",
    "has_more": true
  }
}