**版本：202601**

# 批量创建礼品卡

**POST** `/openapi/2026-01/gift_cards/batch`

批量创建多张礼品卡。

## 请求

**application/json**

**请求体 | 示例**

**请求体 (required)**

- `gift_cards` object[]

  礼品卡列表

  *   Array \[

  - `code` string (required)

    礼品卡码，为字母数字字符串，长度须在 8 到 20 个字符之间
  - `initial_value` string (required)

    礼品卡创建时的初始面值（如 200.00）
  - `expires_on` string

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

    商家可附加到礼品卡上的可选备注，顾客不可见
  - `customer_id` string

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

    用于在线渲染礼品卡的 Liquid 模板后缀
  - `send_email` boolean

    是否向顾客发送通知邮件，默认为 true
  - `currency` string (required)

    礼品卡 ISO 4217 货币代码（如 USD、EUR、CNY）
  - `balance` string

    礼品卡当前余额（如 150.00）
  *   \]

```json
{
  "gift_cards": [
    {
      "code": "string",
      "initial_value": "string",
      "expires_on": "string",
      "note": "string",
      "customer_id": "string",
      "template_suffix": "string",
      "send_email": true,
      "currency": "string",
      "balance": "string"
    }
  ]
}
```

## 响应

**200**

OK

**application/json**

**数据结构 | 示例**

**数据结构**

- `code` string

  错误码
- `message` string

  错误信息
- `data` object

  - `success_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）
    - `currency` string

      礼品卡面值所使用的货币（如 USD、EUR、CNY）
    - `line_item_id` string

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

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

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

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

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

      礼品卡码，由字母数字字符组成（最少 8 个字符，最多 20 个字符）
    *   \]
  - `failed_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）
    - `currency` string

      礼品卡面值所使用的货币（如 USD、EUR、CNY）
    - `line_item_id` string

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

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

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

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

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

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

```json
{
  "code": "string",
  "message": "string",
  "data": {
    "success_gift_cards": [
      {
        "id": "string",
        "last_characters": "string",
        "balance": "string",
        "initial_value": "string",
        "note": "string",
        "expires_on": "string",
        "disabled_at": "string",
        "currency": "string",
        "line_item_id": "string",
        "order_id": "string",
        "user_id": "string",
        "template_suffix": "string",
        "customer_id": "string",
        "code": "string"
      }
    ],
    "failed_gift_cards": [
      {
        "id": "string",
        "last_characters": "string",
        "balance": "string",
        "initial_value": "string",
        "note": "string",
        "expires_on": "string",
        "disabled_at": "string",
        "currency": "string",
        "line_item_id": "string",
        "order_id": "string",
        "user_id": "string",
        "template_suffix": "string",
        "customer_id": "string",
        "code": "string"
      }
    ]
  }
}
```