Update coupon

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

Updates an existing coupon campaign by ID.

Request

Path Parameters

id stringrequired

Coupon ID. Read from the URL path

application/json

Body

Bodyrequired

coupon objectrequired

Updated coupon payload

titlestring

The updated coupon title

remarksstring

The updated merchant-side remark

starts_atint64

Updated distribution start timestamp

ends_atint64

Updated distribution end timestamp. -1 means no expiry

use_coupon_starts_atint64

Updated usage start timestamp

use_coupon_ends_atint64

Updated usage end timestamp

survival_timeint64

Updated survival duration

unlimited_usageboolean

Whether the coupon quantity is unlimited. true means unlimited, false means limited. Defaults to false

stockint32

Updated remaining coupon stock. Required when unlimited_usage is false

sort object

Updated product sort options

bystring

The field used to sort selected products. Defaults to title:

• title: Sort by product title
• price: Sort by product price
• sales: Sort by sales volume
• real_sales: Sort by real sales volume

directionstring

The sort direction. Defaults to asc:

• asc: Ascending order
• desc: Descending order

config object

Updated storefront configuration

banner_urlstring

The banner image URL

count_down object

Countdown presentation configuration

background_color_endstring

The ending background color of the countdown banner

background_color_startstring

The starting background color of the countdown banner

colorstring

The primary text color in coupon countdown components

count_down_background_colorstring

The background color of the countdown timer block

count_down_colorstring

The text color of the countdown timer value

detail_page_show_codeboolean

Whether coupon code is shown on the detail page countdown area

show_count_downboolean

Whether countdown visualization is enabled

Example

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

Responses

200

OK

application/json

Schema

Schema

codestring

error code

messagestring

error message

data object

coupon object

The updated coupon payload

idstring

Coupon ID

titlestring

Coupon title displayed to merchants

remarksstring

Merchant-side note

life_cycle_typestring

Coupon lifecycle type:

• begin_end: Uses explicit start and end timestamps
• survival: Uses survival_time after claiming

starts_atint64

Distribution start timestamp

ends_atint64

Distribution end timestamp

use_coupon_starts_atint64

Usage start timestamp

use_coupon_ends_atint64

Usage end timestamp

survival_timeint64

Valid duration after claiming

discount_typestring

Discount threshold strategy type:

• percentage: Percentage discount with no-condition or quantity condition
• amount_percentage: Percentage discount with amount condition
• fixed_amount: Fixed amount discount with no-condition or amount condition
• item_fixed_amount: Fixed amount discount with quantity condition

valuestring

Discount value

value_typestring

Discount value type:

• percentage: Percentage discount
• fixed_amount: Fixed amount reduction
• voucher: Free voucher style benefit

unlimited_usageboolean

Whether the coupon quantity is unlimited

stockint32

Remaining coupon stock

once_per_customerint32

Maximum claims per customer

user_with_otherboolean

Whether this coupon can be used with other discounts

prerequisite_subtotal_range object[]

Amount-based prerequisite ranges

Array [

greater_than_or_equal_tostring

The lower bound of the threshold, inclusive

valuestring

The threshold value represented as a string

]

prerequisite_quantity_range object[]

Quantity-based prerequisite ranges

Array [

greater_than_or_equal_tostring

The lower bound of the threshold, inclusive

valuestring

The threshold value represented as a string

]

entitled_product_idsstring[]

Product IDs eligible for this coupon

entitled_collection_idsstring[]

Collection IDs eligible for this coupon

prerequisite_customer_segment_idsstring[]

Eligible customer segment IDs

prerequisite_customer_idsstring[]

Eligible customer IDs

sort object

Sort options for selected products

bystring

The field used to sort selected products

directionstring

The sort direction, for example asc or desc

config object

Storefront visual configuration

banner_urlstring

The banner image URL

count_down object

Countdown presentation configuration

background_color_endstring

The ending background color of the countdown banner

background_color_startstring

The starting background color of the countdown banner

colorstring

The primary text color in coupon countdown components

count_down_background_colorstring

The background color of the countdown timer block

count_down_colorstring

The text color of the countdown timer value

detail_page_show_codeboolean

Whether coupon code is shown on the detail page countdown area

show_count_downboolean

Whether countdown visualization is enabled

Example

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