创建优惠券

POST 
/openapi/2027-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

优惠券前台展示视觉配置

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

是否启用倒计时可视化

示例

json

{
  "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": {
      "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
      }
    }
  }
}

响应

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

是否启用倒计时可视化

示例

json

{
  "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
        }
      }
    }
  }
}