get https://{subdomain}.myshoplaza.com/openapi/2022-01/coupons
Requires
price_rulesaccess scope. More access scope
The Coupon List API retrieves a paginated list of coupons available in the system.
This API is especially useful for:
- Listing all coupons based on progress or type filters.
- Searching for specific coupons by keywords.
- Paginating through large sets of coupons efficiently.
Request Parameters
Public Request Parameters
Query Parameters
| Parameter | Type | Example | Description |
|---|---|---|---|
page | int32 | 1 | Page number for paginated results. |
limit | int32 | 10 | Number of coupons per page. |
progress | string | ongoing | Filter by progress of coupons. Available values: not_started, ongoing, finished. |
type | string | percentage | Filter by type of coupons. Available values: fixed_amount, percentage. |
keywords | string | coupon1 | Search for coupons by title. |
Response Explanation
Public Response Parameters
Success Response
| Field | Type | Description | Example |
|---|---|---|---|
page | integer | Current page number. | 0 |
limit | integer | Number of records per page. | 10 |
total | integer | Total number of records. | 2 |
data | array | List of discount data. | [...] |
data.id | string | Unique identifier for the discount. | "202314454241654711" |
data.store_id | integer | Store ID where the discount is applicable. | 11218 |
data.life_cycle_type | string | Lifecycle type of the discount. Can be begin_end or survival. | "begin_end" |
data.survival_time | integer | Valid time (in seconds). Relevant for life_cycle_type=survival. | 86400 |
data.starts_at | integer | Discount start time in UNIX timestamp. | 1673246985 |
data.ends_at | integer | Discount end time in UNIX timestamp, -1 for no end date. | -1 |
data.status | integer | Status of the discount (internal field, to be deprecated). | 0 |
data.discount_type | DiscountType | Type of discount. | "percentage" |
data.value_type | string | Type of discount value. | "percentage" |
data.value | string | Rule discount value. For thresholds, this is 0. | "10" |
data.usage_limit | integer | Maximum usage limit for the discount. -1 for unlimited. | -1 |
data.once_per_customer | integer | Maximum number of times the discount can be used by a single customer. | 0 |
data.title | string | Title or name of the discount. | "coupon1" |
data.stock | integer | Remaining stock or availability of the discount. | 0 |
data.code | string | Discount code, if applicable. | "" |
data.prerequisite | integer | Indicates whether the discount has prerequisites (1 for yes, 0 for no). | 0 |
data.is_admin_show | integer | Indicates if the discount is visible in admin (1 for yes, 0 for no). | 0 |
data.target_selection | string | Target range (e.g., all for all products). | "all" |
data.progress | string | Coupon status (use this field instead of status).Activity status: ongoing in progress, not_started not started, finished ended, | "ongoing" |
data.using_state | ## Deprecated:## Internal field for coupon status. Use progress instead. | "" | |
data.allocation_limit_amount | string | Maximum allocation limit amount for the discount. | "0" |
data.entitled_area_list | array | List of areas entitled for the discount. | [] |
data.prerequisite_quantity_range | array of object | Quantity range prerequisites for the discount. | [{"greater_than_or_equal_to": ""}] |
data.prerequisite_subtotal_range | array of object | Subtotal range prerequisites for the discount. | [{"greater_than_or_equal_to": ""}] |
data.entitled_product_ids | array | List of product IDs entitled for the discount. | [] |
data.entitled_variant_ids | array | List of variant IDs entitled for the discount. | [] |
data.entitled_sort | array | Sorting order for entitled products. | [] |
data.times_used | integer | Number of times the discount has been used. | 1 |
data.sort | object | Sorting configuration for the discount. | {"by": "sales", "direction": "desc"} |
data.use_with_other | integer | Indicates if the discount can be used with other discounts (1 for yes, 0 for no). | 0 |
data.prerequisite_customer_ids | array | List of customer IDs eligible for the discount. | [] |
data.prerequisite_customer_segment_ids | array | List of customer segment IDs eligible for the discount. | [] |
data.config | object | Discount configuration, including banner and countdown settings. | {"banner_url": "", "count_down": {...}} |
data.allocation_method | string | Allocation method for the discount. | "" |
data.allocation_limit | integer | Allocation limit for the discount. | 0 |
data.customer_selection | string | Customer selection criteria for the discount. | "" |
data.entitled_collection_ids | array | List of collection IDs entitled for the discount. | [] |
data.tips | object | Tips and messages associated with the discount. | {"msg": "", "countdown": ""} |
data.entitled_extra_list | null | Additional entitled data for the discount. | null |
data.prerequisite_customer_range | null | Customer range prerequisites for the discount. | null |
data.buysPrerequisiteValue | integer | Buy prerequisite value for the discount. | 0 |
data.getsMaxOrderUseValue | integer | Maximum order use value for the discount. | 0 |
data.getsDiscountValue | integer | Discount value to be applied. | 0 |
data.only_valid_first_order_customer | boolean | Indicates if the discount is valid for first order customers only. | false |
Error Response
Error responses in the API can be represented using two different fields: errors and error. Both fields provide details about issues encountered during request processing. Below is an explanation of the fields with their respective examples and descriptions.
| Field | Type | Example | Description |
|---|---|---|---|
errors | Array | [ "invalid line_item id"] | A list of errors encountered during the request processing. |
| Field | Type | Example | Description |
|---|---|---|---|
error | String | "store is not active" | Indicates an error encountered during the process |
Error Detail
| Status Code | Message | Possible Reason | Example Response |
|---|---|---|---|
| 400 | Bad Request | Invalid input format or request structure (e.g., missing required fields or incorrect data types). | Bad Request |
| Unauthorized | The request is missing valid authentication credentials or the credentials provided are invalid. | Unauthorized |