🔒
Requires price_rules access scope.

The Coupon List API retrieves a paginated list of coupons available in the system.

This API is especially useful for:

Displaying available coupons in storefronts
Managing coupon campaigns in admin panels
Implementing coupon search functionality
Analyzing coupon performance and usage

Request Parameters

Public Request Parameters

📘
Public Request Parameters

Query Parameters

Parameter	Type	Required	Description	Example
`cursor`	string	No	Cursor for pagination	`"abc123"`
`page_size`	int32	No	Number of records per page (default: 10)	`20`
`progress`	string	No	Filter by coupon progress (`not_started`, `ongoing`, `finished`)	`"ongoing"`
`type`	string	No	Filter by coupon type (`fixed_amount`, `percentage`, `voucher`)	`"percentage"`
`keywords`	string	No	Search coupons by title	`"summer sale"`

Response Explanation

Public Response Parameters

📘
Public Response Parameters

Successful Response

Parameter	Type	Example	Description
`code`	string	`"success"`	Status code of the response
`message`	string		Descriptive message of the response
`data.coupons`	array[object]	-	Array of coupon objects
`data.cursor`	string	`"next_page_token"`	Pagination cursor
`data.has_more`	boolean	`true`	Whether more coupons exist

Coupon Object

Parameter	Type	Example	Description
`id`	string	`"coupon_123"`	Unique coupon identifier
`store_id`	integer	`12345`	Store ID
`life_cycle_type`	string	`"date_range"`	Coupon lifecycle type
`survival_time`	string	`"P30D"`	Duration coupon is valid
`starts_at`	string	`"2025-06-01T00:00:00Z"`	Start datetime
`ends_at`	string	`"2025-06-30T23:59:59Z"`	End datetime
`discount_type`	string	`"percentage"`	Discount type
`value_type`	string	`"fixed"`	Value type
`value`	string	`"20.00"`	Discount value
`usage_limit`	integer	`100`	Maximum usage limit
`once_per_customer`	integer	`1`	Limit one per customer
`title`	string	`"Summer Sale"`	Coupon title
`stock`	integer	`50`	Remaining stock
`target_selection`	string	`"entitled_products"`	What coupon applies to
`code`	string	`"SUMMER20"`	Coupon code
`prerequisite`	integer	`1`	Whether has prerequisites
`is_admin_show`	integer	`1`	Visible in admin
`progress`	string	`"ongoing"`	Coupon progress status
`allocation_limit_amount`	string	`"100.00"`	Allocation limit amount
`prerequisite_quantity_range`	array[object]	-	Quantity requirements (see below)
`prerequisite_subtotal_range`	array[object]	-	Subtotal requirements (see below)
`entitled_product_ids`	array[string]	`["prod_123"]`	Eligible product IDs
`entitled_variant_ids`	array[string]	`["variant_456"]`	Eligible variant IDs
`entitled_sort`	array[string]	`["popularity"]`	Sort values
`times_used`	integer	`25`	Number of times used
`sort`	object	-	Sorting config (see below)
`use_with_other`	integer	`0`	Combinable with other coupons
`prerequisite_customer_ids`	array[string]	`["cust_789"]`	Eligible customer IDs
`prerequisite_customer_segment_ids`	array[string]	`["segment_123"]`	Customer segment IDs
`config`	object	-	Display config (see below)
`allocation_method`	string	`"manual"`	Allocation method
`allocation_limit`	integer	`1`	Allocation limit
`customer_selection`	string	`"all"`	Customer selection
`entitled_collection_ids`	array[string]	`["coll_123"]`	Eligible collection IDs
`tips`	object	-	Display tips (see below)
`entitled_extra_list`	array[object]	-	Extra entitlements (see below)
`discount_channel_list`	array[object]	-	Channel restrictions (see below)
`only_valid_first_order_customer`	boolean	`true`	First-order only
`target_price_type`	string	`"product_price"`	Target price type
`remarks`	string	`"Summer promotion"`	Remarks
`coupon_type`	string	`"promotion"`	Coupon type
`channel_message`	string	`"Online only"`	Channel message
`coupon_message`	string	`"Save 20%"`	Coupon message
`send_target_selection`	string	`"specific_customers"`	Send target
`effective_time`	string	`"immediate"`	Effective time
`use_coupon_starts_at`	string	`"2025-06-01T00:00:00Z"`	Usage start time
`use_coupon_ends_at`	string	`"2025-06-30T23:59:59Z"`	Usage end time

prerequisite_quantity_range

Parameter	Type	Example	Description
`greater_than_or_equal_to`	string	`"2"`	Minimum quantity
`value`	string	`"10.00"`	Discount value
`value_percentage`	string	`"10"`	Percentage value
`value_event_type`	string	`"discount"`	Event type
`value_condition`	string	`"greater_than"`	Value condition
`target_type`	string	`"product"`	Target type

prerequisite_subtotal_range

Parameter	Type	Example	Description
`greater_than_or_equal_to`	string	`"100.00"`	Minimum subtotal
`value`	string	`"20.00"`	Discount value
`value_percentage`	string	`"20"`	Percentage value
`value_event_type`	string	`"discount"`	Event type
`value_condition`	string	`"greater_than"`	Value condition
`target_type`	string	`"cart"`	Target type

sort

Parameter	Type	Example	Description
`by`	string	`"created_at"`	Sort field
`direction`	string	`"desc"`	Sort direction

config

Parameter	Type	Example	Description
`banner_url`	string	`"https://example.com/banner.jpg"`	Banner URL
`banner_size`	string	`"large"`	Banner size
`count_down. show_count_down`	boolean	`true`	Show countdown
`count_down. format`	string	`"DD:HH:MM"`	Countdown format
`count_down. background_color_start`	string	`"#FF0000"`	Gradient start color
`count_down. background_color_end`	string	`"#00FF00"`	Gradient end color
`count_down. color`	string	`"#FFFFFF"`	Text color
`count_down. count_down_background_color`	string	`"#000000"`	Countdown bg color
`count_down. count_down_color`	string	`"#FFFFFF"`	Countdown text color
`count_down. detail_page_show_code`	boolean	`true`	Show code on detail page
`count_down. landing_page_show_code`	integer	`1`	Show code on landing page

tips

Parameter	Type	Example	Description
`msg`	string	`"Limited time"`	Message text
`countdown`	string	`"3 days left"`	Countdown text
`countdown_day`	string	`"5"`	Countdown days
`use_code`	string	`"Use code SUMMER20"`	Code usage text
`copy_code`	string	`"Copy code"`	Copy code text

Error Response

Field	Type	Example	Description
`code`	string	`InvalidParameter`	Error http message
`message`	string	``	Error message

API Structure Overview

200OK