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 | Example | Description |
|---|---|---|---|
page | int | 1 | Current page of the paginated result set. |
limit | int | 10 | Number of items displayed per page. |
total | int | 2 | Total number of items available. |
data | array | List of coupon objects. Each object contains: | |
data.id | string | "202314454241654711" | Unique identifier of the coupon. |
data.store_id | int | 11218 | Store ID associated with the coupon. |
data.title | string | "coupon1" | Name of the coupon. |
data.value | string | "10" | Value of the discount (percentage or fixed amount). |
data.discount_type | string | "percentage" | Type of discount, e.g., percentage. |
data.stock | int | 0 | Available stock for this coupon. |
data.progress | string | "ongoing" | Current progress status (not_started, ongoing, finished). |
data.times_used | int | 1 | Number of times the coupon has been used. |
data.life_cycle_type | string | "begin_end" | Life cycle type of the coupon. |
data.starts_at | timestamp | 1673246985 | Timestamp when the coupon becomes active. |
data.ends_at | timestamp | -1 | Timestamp when the coupon expires. |
data.usage_limit | int | -1 | Limit on the number of times the coupon can be used. |
data.once_per_customer | boolean | false | Whether the coupon can be used only once per customer. |
data.sort.by | string | "sales" | Sorting criteria (e.g., sales). |
data.sort.direction | string | "desc" | Sorting direction (asc or desc). |
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 |