创建优惠券

POST 
/openapi/2026-01/coupons

创建优惠券活动。

请求

application/json

请求体

请求体必填

coupon object必填

优惠券数据

titlestring必填

商家侧显示的优惠券标题

remarksstring必填

商家侧内部备注

life_cycle_typestring必填

优惠券有效期类型：

• begin_end：使用明确的起止时间
• survival：领取后按 survival_time 计算有效期

starts_atint64必填

优惠券发放开始时间

ends_atint64必填

优惠券发放结束时间，-1 表示永不过期

use_coupon_starts_atint64必填

优惠券使用开始时间

use_coupon_ends_atint64必填

优惠券使用结束时间

survival_timeint64必填

领取优惠券后的有效时长（秒）

discount_typestring必填

折扣门槛策略类型：

• percentage：无门槛或数量门槛的折扣率优惠
• amount_percentage：金额门槛的折扣率优惠
• fixed_amount：无门槛或金额门槛的固定减免优惠
• item_fixed_amount：数量门槛的固定减免优惠

valuestring必填

折扣值，如折扣率或固定减免金额

value_typestring必填

折扣值类型：

• percentage：折扣率
• fixed_amount：固定减免金额
• voucher：免费代金券形式

unlimited_usageboolean

优惠券数量是否不限，true 为不限，false 为有限额，默认 false

stockint32必填

优惠券剩余库存，unlimited_usage 为 false 时必填

once_per_customerint32必填

每位顾客最多领取次数

user_with_otherboolean必填

是否可与其他折扣叠加使用

prerequisite_subtotal_range object[]

金额门槛范围，discount_type 为 amount_percentage 时必填

Array [

greater_than_or_equal_tostring

阈值下限（含）

valuestring

阈值，以字符串表示

]

prerequisite_quantity_range object[]

数量门槛范围，discount_type 为 item_fixed_amount 时必填

Array [

greater_than_or_equal_tostring

阈值下限（含）

valuestring

阈值，以字符串表示

]

entitled_product_idsstring[]

此优惠券适用的商品 ID 列表

entitled_collection_idsstring[]

此优惠券适用的集合 ID 列表

prerequisite_customer_segment_idsstring[]

此优惠券适用的顾客分群 ID 列表

prerequisite_customer_idsstring[]

此优惠券适用的顾客 ID 列表

sort object

已选适用商品的排序配置

bystring

商品排序字段，默认按标题排序：

• title：按商品标题排序
• price：按商品价格排序
• sales：按销售量排序
• real_sales：按实际销售量排序

directionstring

排序方向，默认升序：

• asc：升序
• desc：降序

config object

优惠券前台展示视觉配置

page_typestring

结账页类型（如三页式 three_step）

requires_shippingboolean

指定订单是否需要配送

product_tax_includedboolean

指定商品价格是否含税

market_setting object

指定订单的市场特定配置（如区域税、货币设置）

primary_market_langstring

主要市场语言

market_langstring

市场语言（如 en-US）

market_idstring

市场配置 ID

market_currencystring

市场货币代码（如 USD）

market_currency_symbol object

市场货币符号

codestring

货币代码（如 USD）

valstring

货币符号（如 $）

leftstring

数字左侧显示的内容（如 $）

rightstring

数字右侧显示的内容

market_base_idstring

市场基础 ID

market_base_currencystring

市场基础货币（如 USD）

market_base_currency_symbol object

市场基础货币符号

codestring

货币代码（如 USD）

valstring

货币符号（如 $）

leftstring

数字左侧显示的内容（如 $）

rightstring

数字右侧显示的内容

primary_market_idstring

主要市场 ID

primary_market_currencystring

主要市场货币代码（如 USD）

primary_market_currency_symbol object

主要市场货币符号

codestring

货币代码（如 USD）

valstring

货币符号（如 $）

leftstring

数字左侧显示的内容（如 $）

rightstring

数字右侧显示的内容

market_price_setting object

市场价格设置

local_currency_enabledboolean

本地货币启用状态

custom_rate_enabledboolean

自定义汇率启用状态

custom_ratefloat

自定义汇率：主要市场货币 → 市场基础货币

ratefloat

汇率：主要市场货币 → 市场基础货币/本地货币

back_ratefloat

反向汇率：市场基础货币/本地货币 → 主要市场货币

actual_ratefloat

实际汇率：主要市场货币 → 市场基础货币/本地货币

base_to_ratefloat

汇率：市场基础货币 → 本地货币

local_to_ratefloat

本地汇率

adjustint32

价格调整值

price_round_enabledboolean

启用价格取整

market_countrystring

市场国家（如 US）

示例

{
  "coupon": {
    "title": "string",
    "remarks": "string",
    "life_cycle_type": "string",
    "starts_at": 0,
    "ends_at": 0,
    "use_coupon_starts_at": 0,
    "use_coupon_ends_at": 0,
    "survival_time": 0,
    "discount_type": "string",
    "value": "string",
    "value_type": "string",
    "unlimited_usage": true,
    "stock": 0,
    "once_per_customer": 0,
    "user_with_other": true,
    "prerequisite_subtotal_range": [
      {
        "greater_than_or_equal_to": "string",
        "value": "string"
      }
    ],
    "prerequisite_quantity_range": [
      {
        "greater_than_or_equal_to": "string",
        "value": "string"
      }
    ],
    "entitled_product_ids": [
      "string"
    ],
    "entitled_collection_ids": [
      "string"
    ],
    "prerequisite_customer_segment_ids": [
      "string"
    ],
    "prerequisite_customer_ids": [
      "string"
    ],
    "sort": {
      "by": "string",
      "direction": "string"
    },
    "config": {
      "page_type": "string",
      "requires_shipping": true,
      "product_tax_included": true,
      "market_setting": {
        "primary_market_lang": "string",
        "market_lang": "string",
        "market_id": "string",
        "market_currency": "string",
        "market_currency_symbol": {
          "code": "string",
          "val": "string",
          "left": "string",
          "right": "string"
        },
        "market_base_id": "string",
        "market_base_currency": "string",
        "market_base_currency_symbol": {
          "code": "string",
          "val": "string",
          "left": "string",
          "right": "string"
        },
        "primary_market_id": "string",
        "primary_market_currency": "string",
        "primary_market_currency_symbol": {
          "code": "string",
          "val": "string",
          "left": "string",
          "right": "string"
        },
        "market_price_setting": {
          "local_currency_enabled": true,
          "custom_rate_enabled": true,
          "custom_rate": 0,
          "rate": 0,
          "back_rate": 0,
          "actual_rate": 0,
          "base_to_rate": 0,
          "local_to_rate": 0,
          "adjust": 0,
          "price_round_enabled": true
        },
        "market_country": "string"
      }
    }
  }
}

响应

200

OK

application/json

数据结构

数据结构

codestring

错误码

messagestring

错误信息

data object

coupon object

已创建的优惠券数据

idstring

优惠券 ID

titlestring

商家侧显示的优惠券标题

remarksstring

商家侧备注

life_cycle_typestring

优惠券有效期类型：

• begin_end：使用明确的起止时间
• survival：领取后按 survival_time 计算有效期

starts_atint64

发放开始时间

ends_atint64

发放结束时间

use_coupon_starts_atint64

使用开始时间

use_coupon_ends_atint64

使用结束时间

survival_timeint64

领取后有效时长

discount_typestring

折扣门槛策略类型：

• percentage：无门槛或数量门槛的折扣率优惠
• amount_percentage：金额门槛的折扣率优惠
• fixed_amount：无门槛或金额门槛的固定减免优惠
• item_fixed_amount：数量门槛的固定减免优惠

valuestring

折扣值

value_typestring

折扣值类型：

• percentage：折扣率
• fixed_amount：固定减免金额
• voucher：免费代金券形式

unlimited_usageboolean

优惠券数量是否不限

stockint32

优惠券剩余库存

once_per_customerint32

每位顾客最多领取次数

user_with_otherboolean

是否可与其他折扣叠加使用

prerequisite_subtotal_range object[]

金额门槛范围

Array [

greater_than_or_equal_tostring

阈值下限（含）

valuestring

阈值，以字符串表示

]

prerequisite_quantity_range object[]

数量门槛范围

Array [

greater_than_or_equal_tostring

阈值下限（含）

valuestring

阈值，以字符串表示

]

entitled_product_idsstring[]

此优惠券适用的商品 ID 列表

entitled_collection_idsstring[]

此优惠券适用的集合 ID 列表

prerequisite_customer_segment_idsstring[]

适用的顾客分群 ID 列表

prerequisite_customer_idsstring[]

适用的顾客 ID 列表

sort object

已选商品的排序配置

bystring

商品排序字段

directionstring

排序方向，如 asc（升序）或 desc（降序）

config object

前台展示视觉配置

banner_urlstring

横幅图片 URL

count_down object

倒计时展示配置

background_color_endstring

倒计时横幅背景渐变结束色

background_color_startstring

倒计时横幅背景渐变起始色

colorstring

优惠券倒计时组件主文字颜色

count_down_background_colorstring

倒计时计时器块的背景色

count_down_colorstring

倒计时数值的文字颜色

detail_page_show_codeboolean

详情页倒计时区域是否显示优惠券码

show_count_downboolean

是否启用倒计时可视化

示例

{
  "code": "string",
  "message": "string",
  "data": {
    "coupon": {
      "id": "string",
      "title": "string",
      "remarks": "string",
      "life_cycle_type": "string",
      "starts_at": 0,
      "ends_at": 0,
      "use_coupon_starts_at": 0,
      "use_coupon_ends_at": 0,
      "survival_time": 0,
      "discount_type": "string",
      "value": "string",
      "value_type": "string",
      "unlimited_usage": true,
      "stock": 0,
      "once_per_customer": 0,
      "user_with_other": true,
      "prerequisite_subtotal_range": [
        {
          "greater_than_or_equal_to": "string",
          "value": "string"
        }
      ],
      "prerequisite_quantity_range": [
        {
          "greater_than_or_equal_to": "string",
          "value": "string"
        }
      ],
      "entitled_product_ids": [
        "string"
      ],
      "entitled_collection_ids": [
        "string"
      ],
      "prerequisite_customer_segment_ids": [
        "string"
      ],
      "prerequisite_customer_ids": [
        "string"
      ],
      "sort": {
        "by": "string",
        "direction": "string"
      },
      "config": {
        "banner_url": "string",
        "count_down": {
          "background_color_end": "string",
          "background_color_start": "string",
          "color": "string",
          "count_down_background_color": "string",
          "count_down_color": "string",
          "detail_page_show_code": true,
          "show_count_down": true
        }
      }
    }
  }
}