**版本：202601**

# 查询礼品卡列表

**GET** `/openapi/2026-01/gift_cards`

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

## 请求

**Query参数**

- `cursor` string

  分页游标
- `page_size` int32

  每页记录数，默认为 10
- `page` int32

  页码（从 1 开始），与 cursor 互斥
- `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**

**数据结构 | 示例**

**数据结构**

- `code` string

  错误码
- `message` string

  错误信息
- `data` object

  - `gift_cards` object[]

    礼品卡列表

    *   Array \[

    - `id` string

      礼品卡 ID
    - `last_characters` string

      礼品卡码的后四位
    - `balance` string

      礼品卡当前余额
    - `initial_value` string

      礼品卡的初始面值
    - `note` string

      附加在礼品卡上的备注
    - `expires_on` string

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

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

      礼品卡当前是否已启用
    - `created_at` string

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

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

      礼品卡状态：

      *   `enable`: 启用，礼品卡可正常使用
      *   `disable`: 禁用，礼品卡不可用
    - `currency` string

      礼品卡面值所使用的货币
    - `line_item_id` string

      与礼品卡关联的商品行项目 ID
    - `order_id` string

      与礼品卡关联的订单 ID
    - `user_id` string

      礼品卡创建者或所有者的用户 ID
    - `template_suffix` string

      用于在线渲染礼品卡的模板后缀
    - `customer_id` string

      与礼品卡关联的顾客 ID
    - `code` string

      礼品卡码，由字母数字字符组成（最少 8 个字符，最多 20 个字符）
    *   \]
  - `cursor` string

    分页游标
  - `has_more` boolean

    是否有更多记录
  - `total` int32

    全部页的总记录数(供 page 模式分页计算总页数)

```json
{
  "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,
    "total": 0
  }
}
```