**版本：202701**

# 更新优惠券

**PUT** `/openapi/2027-01/coupons/:id`

通过 ID 更新现有优惠券活动。

## 请求

**Path参数**

- `id` string (required)

  优惠券 ID，从 URL 路径读取

**application/json**

**请求体 | 示例**

**请求体 (required)**

- `coupon` object (required)

  更新后的优惠券数据

  - `title` string

    更新后的优惠券标题
  - `remarks` string

    更新后的商家侧备注
  - `starts_at` int64

    更新后的发放开始时间
  - `ends_at` int64

    更新后的发放结束时间，-1 表示永不过期
  - `use_coupon_starts_at` int64

    更新后的使用开始时间
  - `use_coupon_ends_at` int64

    更新后的使用结束时间
  - `survival_time` int64

    更新后的有效时长
  - `unlimited_usage` boolean

    优惠券数量是否不限，true 为不限，false 为有限额
  - `stock` int32

    更新后的优惠券库存，unlimited\_usage 为 false 时必填
  - `sort` object

    更新后的商品排序配置

    - `by` string

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

      *   `title`：按商品标题排序
      *   `price`：按商品价格排序
      *   `sales`：按销售量排序
      *   `real_sales`：按实际销售量排序
    - `direction` string

      排序方向，默认升序：

      *   `asc`：升序
      *   `desc`：降序
  - `config` object

    更新后的前台展示配置

    - `banner_url` string

      横幅图片 URL
    - `count_down` object

      倒计时展示配置

      - `background_color_end` string

        倒计时横幅背景渐变结束色
      - `background_color_start` string

        倒计时横幅背景渐变起始色
      - `color` string

        优惠券倒计时组件主文字颜色
      - `count_down_background_color` string

        倒计时计时器块的背景色
      - `count_down_color` string

        倒计时数值的文字颜色
      - `detail_page_show_code` boolean

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

        是否启用倒计时可视化

```json
{
  "coupon": {
    "title": "string",
    "remarks": "string",
    "starts_at": 0,
    "ends_at": 0,
    "use_coupon_starts_at": 0,
    "use_coupon_ends_at": 0,
    "survival_time": 0,
    "unlimited_usage": true,
    "stock": 0,
    "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**

**数据结构 | 示例**

**数据结构**

- `code` string

  错误码
- `message` string

  错误信息
- `data` object

  - `coupon` object

    已更新的优惠券数据

    - `id` string

      优惠券 ID
    - `title` string

      商家侧显示的优惠券标题
    - `remarks` string

      商家侧备注
    - `life_cycle_type` string

      优惠券有效期类型：

      *   `begin_end`：使用明确的起止时间
      *   `survival`：领取后按 survival\_time 计算有效期
    - `starts_at` int64

      发放开始时间
    - `ends_at` int64

      发放结束时间
    - `use_coupon_starts_at` int64

      使用开始时间
    - `use_coupon_ends_at` int64

      使用结束时间
    - `survival_time` int64

      领取后有效时长
    - `discount_type` string

      折扣门槛策略类型：

      *   `percentage`：无门槛或数量门槛的折扣率优惠
      *   `amount_percentage`：金额门槛的折扣率优惠
      *   `fixed_amount`：无门槛或金额门槛的固定减免优惠
      *   `item_fixed_amount`：数量门槛的固定减免优惠
    - `value` string

      折扣值
    - `value_type` string

      折扣值类型：

      *   `percentage`：折扣率
      *   `fixed_amount`：固定减免金额
      *   `voucher`：免费代金券形式
    - `unlimited_usage` boolean

      优惠券数量是否不限
    - `stock` int32

      优惠券剩余库存
    - `once_per_customer` int32

      每位顾客最多领取次数
    - `user_with_other` boolean

      是否可与其他折扣叠加使用
    - `prerequisite_subtotal_range` object[]

      金额门槛范围

      *   Array \[

      - `greater_than_or_equal_to` string

        阈值下限（含）
      - `value` string

        阈值，以字符串表示
      *   \]
    - `prerequisite_quantity_range` object[]

      数量门槛范围

      *   Array \[

      - `greater_than_or_equal_to` string

        阈值下限（含）
      - `value` string

        阈值，以字符串表示
      *   \]
    - `entitled_product_ids` string[]

      此优惠券适用的商品 ID 列表
    - `entitled_collection_ids` string[]

      此优惠券适用的集合 ID 列表
    - `prerequisite_customer_segment_ids` string[]

      适用的顾客分群 ID 列表
    - `prerequisite_customer_ids` string[]

      适用的顾客 ID 列表
    - `sort` object

      已选商品的排序配置

      - `by` string

        商品排序字段
      - `direction` string

        排序方向，如 asc（升序）或 desc（降序）
    - `config` object

      前台展示视觉配置

      - `banner_url` string

        横幅图片 URL
      - `count_down` object

        倒计时展示配置

        - `background_color_end` string

          倒计时横幅背景渐变结束色
        - `background_color_start` string

          倒计时横幅背景渐变起始色
        - `color` string

          优惠券倒计时组件主文字颜色
        - `count_down_background_color` string

          倒计时计时器块的背景色
        - `count_down_color` string

          倒计时数值的文字颜色
        - `detail_page_show_code` boolean

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

          是否启用倒计时可视化

```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
        }
      }
    }
  }
}
```