List coupons

GET 
/openapi/2025-06/coupons

Retrieves a paginated list of coupons available in the system.

Request

Query Parameters

cursor string

Cursor for pagination

page_size int32

Number of records per page. The default value is 10

progress string
Filter by coupon progress:
• not_started: Not started
• ongoing: In progress
• finished: Ended
type string
Filter by coupon type:
• fixed_amount: Fixed amount discount
• percentage: Percentage discount
• voucher: Voucher
keyword string

Search for coupons by title

Responses

200

OK

application/json

Schema

Schema

codestring

error code

messagestring

error message

data object

coupons object[]

List of coupons

Array [

idstring

Coupon ID

store_idint32

Store ID where the discount is applicable

life_cycle_typestring

Lifecycle type of the discount. Can be begin_end or survival

survival_timestring

Valid time (in seconds). Relevant for life_cycle_type=survival

starts_atstring

Discount start time in UNIX timestamp

ends_atstring

Discount end time in UNIX timestamp, -1 for no end date

discount_typestring

Type of discount

value_typestring

Type of discount value

valuestring

Discount value (e.g., percentage rate or fixed amount). This field is 0 when the discount is determined by threshold rules in prerequisite_subtotal_range or prerequisite_quantity_range

usage_limitint32

Maximum usage limit for the discount. -1 for unlimited

once_per_customerint32

Maximum number of times the discount can be used by a single customer

titlestring

Title or name of the discount

stockint32

Remaining stock or availability of the discount

target_selectionstring

Target range (e.g., all for all products)

codestring

Discount code

prerequisiteint32

Indicates whether the discount has prerequisites (1 for yes, 0 for no)

is_admin_showint32

Indicates if the discount is visible in admin (1 for yes, 0 for no)

progressstring

Coupon progress status. Use this field instead of status:

• ongoing: In progress
• not_started: Not started
• finished: Ended

allocation_limit_amountstring

Maximum allocation limit amount for the discount

prerequisite_quantity_range object[]

Quantity range prerequisites for the discount

Array [

greater_than_or_equal_tostring

Greater than or equal to value

valuestring

The value

value_percentagestring

Percentage value

value_event_typestring

Value event type

value_conditionstring

Value condition

target_typestring

Target type

target_datastring[]

Target data

]

prerequisite_subtotal_range object[]

Subtotal range prerequisites for the discount

Array [

greater_than_or_equal_tostring

Greater than or equal to value

valuestring

The value

value_percentagestring

Percentage value

value_event_typestring

Value event type

value_conditionstring

Value condition

target_typestring

Target type

target_datastring[]

Target data

]

entitled_product_idsstring[]

List of product IDs entitled for the discount

entitled_variant_idsstring[]

List of variant IDs entitled for the discount

entitled_sortstring[]

Sorting order for entitled products

times_usedint32

Number of times the discount has been used

sort object

Sorting configuration for the discount

bystring

Sort field

directionstring

Sort direction

use_with_otherint32

Indicates if the discount can be used with other discounts (1 for yes, 0 for no)

prerequisite_customer_idsstring[]

List of customer IDs eligible for the discount

prerequisite_customer_segment_idsstring[]

List of customer segment IDs eligible for the discount

config object

Discount configuration, including banner and countdown settings

banner_urlstring

Banner URL

banner_sizestring

Banner size

count_down object

Countdown style setting

show_count_downboolean

Whether to show countdown

formatstring

Countdown display format

background_color_startstring

Background gradient start color

background_color_endstring

Background gradient end color

colorstring

Countdown text color

count_down_background_colorstring

Countdown background color

count_down_colorstring

Countdown color

detail_page_show_codeboolean

Detail page show code

landing_page_show_codeint32

Landing page show code

allocation_methodstring

Allocation method for the discount

allocation_limitint32

Allocation limit for the discount

customer_selectionstring

Customer selection criteria for the discount

entitled_collection_idsstring[]

List of collection IDs entitled for the discount

tips object

Tips and messages associated with the discount

msgstring

Message

countdownstring

Countdown

countdown_daystring

Countdown in days

use_codestring

Use code

copy_codestring

Copy code

entitled_extra_list object[]

Additional entitled data for the discount

Array [

idstring

ID

sortint32

Sort configuration

]

discount_channel_list object[]

List of discount channels

Array [

channel_typestring

Type of channel

channel_statusint32

Status of channel

location_idsstring[]

List of location IDs

]

only_valid_first_order_customerboolean

Indicates if the discount is valid for first order customers only

target_price_typestring

Target price type

remarksstring

Remarks

coupon_typestring

Coupon type

channel_messagestring

Channel message

coupon_messagestring

Coupon message

send_target_selectionstring

Send target selection

effective_timestring

Effective time

use_coupon_starts_atstring

Coupon use start timestamp

use_coupon_ends_atstring

Coupon use end timestamp

]

cursorstring

The cursor for the next page of results

has_moreboolean

Whether there are more records

Example

{
  "code": "string",
  "message": "string",
  "data": {
    "coupons": [
      {
        "id": "string",
        "store_id": 0,
        "life_cycle_type": "string",
        "survival_time": "string",
        "starts_at": "string",
        "ends_at": "string",
        "discount_type": "string",
        "value_type": "string",
        "value": "string",
        "usage_limit": 0,
        "once_per_customer": 0,
        "title": "string",
        "stock": 0,
        "target_selection": "string",
        "code": "string",
        "prerequisite": 0,
        "is_admin_show": 0,
        "progress": "string",
        "allocation_limit_amount": "string",
        "prerequisite_quantity_range": [
          {
            "greater_than_or_equal_to": "string",
            "value": "string",
            "value_percentage": "string",
            "value_event_type": "string",
            "value_condition": "string",
            "target_type": "string",
            "target_data": [
              "string"
            ]
          }
        ],
        "prerequisite_subtotal_range": [
          {
            "greater_than_or_equal_to": "string",
            "value": "string",
            "value_percentage": "string",
            "value_event_type": "string",
            "value_condition": "string",
            "target_type": "string",
            "target_data": [
              "string"
            ]
          }
        ],
        "entitled_product_ids": [
          "string"
        ],
        "entitled_variant_ids": [
          "string"
        ],
        "entitled_sort": [
          "string"
        ],
        "times_used": 0,
        "sort": {
          "by": "string",
          "direction": "string"
        },
        "use_with_other": 0,
        "prerequisite_customer_ids": [
          "string"
        ],
        "prerequisite_customer_segment_ids": [
          "string"
        ],
        "config": {
          "banner_url": "string",
          "banner_size": "string",
          "count_down": {
            "show_count_down": true,
            "format": "string",
            "background_color_start": "string",
            "background_color_end": "string",
            "color": "string",
            "count_down_background_color": "string",
            "count_down_color": "string",
            "detail_page_show_code": true,
            "landing_page_show_code": 0
          }
        },
        "allocation_method": "string",
        "allocation_limit": 0,
        "customer_selection": "string",
        "entitled_collection_ids": [
          "string"
        ],
        "tips": {
          "msg": "string",
          "countdown": "string",
          "countdown_day": "string",
          "use_code": "string",
          "copy_code": "string"
        },
        "entitled_extra_list": [
          {
            "id": "string",
            "sort": 0
          }
        ],
        "discount_channel_list": [
          {
            "channel_type": "string",
            "channel_status": 0,
            "location_ids": [
              "string"
            ]
          }
        ],
        "only_valid_first_order_customer": true,
        "target_price_type": "string",
        "remarks": "string",
        "coupon_type": "string",
        "channel_message": "string",
        "coupon_message": "string",
        "send_target_selection": "string",
        "effective_time": "string",
        "use_coupon_starts_at": "string",
        "use_coupon_ends_at": "string"
      }
    ],
    "cursor": "string",
    "has_more": true
  }
}