Create coupon

POST 
/openapi/2026-07/coupons

Creates a coupon campaign.

Request

application/json

Body

Bodyrequired

coupon objectrequired

Coupon payload

titlestringrequired

The coupon title displayed to merchants

remarksstringrequired

Internal note for merchant-side management

life_cycle_typestringrequired

Coupon lifecycle type:

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

starts_atint64required

Coupon distribution start timestamp

ends_atint64required

Coupon distribution end timestamp. -1 means no expiry

use_coupon_starts_atint64required

Coupon usage start timestamp

use_coupon_ends_atint64required

Coupon usage end timestamp

survival_timeint64required

Valid duration in seconds after receiving the coupon

discount_typestringrequired

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

valuestringrequired

Discount value, such as percentage or fixed amount

value_typestringrequired

Discount value type:

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

unlimited_usageboolean

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

stockint32required

Remaining coupon stock. Required when unlimited_usage is false

once_per_customerint32required

Maximum receive count per customer

user_with_otherbooleanrequired

Whether this coupon can be used with other discounts

prerequisite_subtotal_range object[]

Amount-based prerequisite ranges. Required when discount_type is amount_percentage

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. Required when discount_type is item_fixed_amount

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 explicitly eligible for this coupon

entitled_collection_idsstring[]

Collection IDs explicitly eligible for this coupon

prerequisite_customer_segment_idsstring[]

Customer segment IDs eligible for this coupon

prerequisite_customer_idsstring[]

Explicit customer IDs eligible for this coupon

sort object

Sort options for selected entitled products

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

Coupon storefront visual configuration

page_typestring

Checkout page type (e.g., three_step)

requires_shippingboolean

Specifies whether the order requires shipping

product_tax_includedboolean

Indicates whether product prices include taxes

market_setting object

Specifies market-specific configurations for the order (e.g., regional taxes, currency settings)

primary_market_langstring

Primary market language

market_langstring

Market language (e.g., en-US)

market_idstring

Market configuration ID

market_currencystring

Market currency code (e.g., USD)

market_currency_symbol object

Market currency symbol

codestring

Currency code (e.g., USD)

valstring

Currency symbol (e.g., $)

leftstring

Content displayed to the left of the number (e.g., $)

rightstring

Content displayed to the right of the number

market_base_idstring

Market base ID

market_base_currencystring

Market base currency (e.g., USD)

market_base_currency_symbol object

Market base currency symbol

codestring

Currency code (e.g., USD)

valstring

Currency symbol (e.g., $)

leftstring

Content displayed to the left of the number (e.g., $)

rightstring

Content displayed to the right of the number

primary_market_idstring

Primary market ID

primary_market_currencystring

Primary market currency code (e.g., USD)

primary_market_currency_symbol object

Primary market currency symbol

codestring

Currency code (e.g., USD)

valstring

Currency symbol (e.g., $)

leftstring

Content displayed to the left of the number (e.g., $)

rightstring

Content displayed to the right of the number

market_price_setting object

Market price settings

local_currency_enabledboolean

Local currency enable status

custom_rate_enabledboolean

Custom rate enable status

custom_ratefloat

Custom rate: primary market currency to market base currency

ratefloat

Rate: primary market currency to market base currency or local currency

back_ratefloat

Back rate: market base currency or local currency to primary market currency

actual_ratefloat

Actual exchange rate: primary market currency to market base currency or local currency

base_to_ratefloat

Rate: market base currency to local currency

local_to_ratefloat

Local to rate

adjustint32

Price adjustment

price_round_enabledboolean

Enable price rounding

market_countrystring

Market country (e.g., US)

Example

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

Responses

200

OK

application/json

Schema

Schema

codestring

error code

messagestring

error message

data object

coupon object

The created 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

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