创建礼品卡

POST 
/openapi/2026-07/gift_cards

使用提供的详情创建新礼品卡。

请求

application/json

请求体

请求体必填

gift_card object必填

礼品卡

codestring必填

礼品卡码，为字母数字字符串，长度须在 8 到 20 个字符之间

initial_valuestring必填

礼品卡创建时的初始面值（如 200.00）

expires_onstring

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

notestring

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

customer_idstring

与该礼品卡关联的顾客 ID

template_suffixstring

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

send_emailboolean

是否向顾客发送通知邮件，默认为 true

currencystring

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

示例

{
  "gift_card": {
    "code": "string",
    "initial_value": "string",
    "expires_on": "string",
    "note": "string",
    "customer_id": "string",
    "template_suffix": "string",
    "send_email": true,
    "currency": "string"
  }
}

响应

200

OK

application/json

数据结构

数据结构

codestring

错误码

messagestring

错误信息

data object

gift_card object

礼品卡

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 个字符）

示例

{
  "code": "string",
  "message": "string",
  "data": {
    "gift_card": {
      "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"
    }
  }
}