post https://{subdomain}.myshoplaza.com/openapi/2022-01/price_rules
Requires
price_rules
access scope. More access scope
The Create Price Rule API allows you to create a new price rule for discounts or promotions on the store.
This API is especially useful for:
- Managing discounts and promotional campaigns.
- Creating conditional offers based on cart total or product quantity.
- Automating discount rules for specific products or product variants.
Request Parameters
Public Request Parameters
Body Parameters
Field | Type | Required | Description | Example |
---|---|---|---|---|
title | string | Yes | Title of this price rule. | "Discount Rule Title" |
value | double | Yes | Value for this discount. | 50.25 |
value_type | string | Yes | Discount type. Options: fixed_amount for a fixed discount, or percentage for a percentage discount. | "fixed_amount" |
usage_limit | int32 | No | The usage limit. -1 means no limit. | -1 |
allocation_limit | int32 | No | Redeem count limit per checkout: 0 means only one redeem allowed, 999 means no limit. | 0 |
once_per_customer | int32 | No | Maximum usage per customer. -1 or 0 means no limit. | 1 |
prerequisite | int32 | No | Indicates if this discount has prerequisites. 1 means yes, 0 means no. | 1 |
target_selection | string | Yes | Target products allowed for this discount. Options: all for all products, entitled for specific products. | "entitled" |
target_type | string | No | Target type of this discount. | "line_item" |
starts_at | string | Yes | Start time of the discount. | "2024-12-01T00:00:00Z" |
ends_at | string | Yes | End time of the discount. | "2024-12-31T23:59:59Z" |
entitled_product_ids | array[string] | No | Specifies the product IDs allowed for the price rule. Required only when target_selection is entitled . | ["ce21d85-a419-4d4e-a17d-5bddbc4ab7f6", "de2c55f5-3c81-45e1-9276-e65faf816ecc"] |
entitled_variant_ids | array[string] | No | Specifies the product variant IDs allowed for the price rule. | ["ce21d85-a419-4d4e-a17d-5bddbc4ab7f6"] |
prerequisite_subtotal_range | array[object] | No | Prerequisite for total amount in the cart. | [{"greater_than_or_equal_to":"100","value":"10"}] |
prerequisite_subtotal_range.greater_than_or_equal_to | string | Yes | Specifies the minimum total cart amount required. | "100" |
prerequisite_subtotal_range.value | string | Yes | Value used for discount application. | "10" |
prerequisite_subtotal_range.target_type | string | No | Specifies the type of target the rule applies to. | "" |
prerequisite_subtotal_range.target_data | array[string] | No | Specifies IDs of specific target items for the rule. | [] |
prerequisite_quantity_range | array[object] | No | Prerequisite for total quantity of products in the cart. | [{"greater_than_or_equal_to":"5","value":"20"}] |
prerequisite_quantity_range.greater_than_or_equal_to | string | Yes | Specifies the minimum total product quantity required. | "5" |
prerequisite_quantity_range.value | string | Yes | Value used for discount application. | "20" |
prerequisite_quantity_range.target_type | string | No | Specifies the type of target the rule applies to. | "" |
prerequisite_quantity_range.target_data | array[string] | No | Specifies IDs of specific target items for the rule. | [] |
Response Explanation
Public Response Parameters
Successful Response
Field | Type | Description | Example |
---|---|---|---|
page | int | Current page number in the response. | 0 |
limit | int | Number of items per page. | 10 |
total | int | Total number of coupons. | 2 |
data | array | List of coupon objects. | [ ... ] |
data.id | string | Unique identifier for the coupon. | "202314454241654711" |
data.store_id | int | ID of the store associated with the coupon. | 11218 |
data.life_cycle_type | string | Lifecycle type of the coupon. | "begin_end" |
data.survival_time | int | Survival time of the coupon in seconds. | 86400 |
data.starts_at | int | Start time of the coupon (Unix timestamp). | 1673246985 |
data.ends_at | int | End time of the coupon (-1 indicates no end time). | -1 |
data.status | Internal field for coupon status. This field is planned for deprecation in future updates. Please use the progress field to determine the current state of the coupon. | ||
data.discount_type | string | Type of discount. | "percentage" |
data.value_type | string | Value type of the discount. | "percentage" |
data.value | string | Discount value. | "10" |
data.usage_limit | int | Limit on the number of times the coupon can be used (-1 for unlimited). | -1 |
data.once_per_customer | int | Whether the coupon can only be used once per customer. | 0 |
data.title | string | Title of the coupon. | "coupon1" |
data.stock | int | Current stock of the coupon. | 0 |
data.code | string | Code of the coupon. | "" |
data.prerequisite | int | Prerequisite value for the coupon. | 0 |
data.is_admin_show | int | Whether the coupon is visible to the admin. | 0 |
data.target_selection | string | Target selection for the coupon. | "all" |
data.progress | string | Current progress of the coupon. | "ongoing" |
data.using_state | string | Current state of coupon usage. | "" |
data.allocation_limit_amount | string | Allocation limit amount for the coupon. | "0" |
data.entitled_area_list | array | List of entitled areas for the coupon. | [] |
data.prerequisite_quantity_range | array | Prerequisite quantity range for the coupon. | [ ... ] |
data.prerequisite_subtotal_range | array | Prerequisite subtotal range for the coupon. | [ ... ] |
data.entitled_product_ids | array | List of entitled product IDs. | [] |
data.entitled_variant_ids | array | List of entitled variant IDs. | [] |
data.entitled_sort | array | Sort criteria for entitled items. | [] |
data.times_used | int | Number of times the coupon has been used. | 1 |
data.sort.by | string | Sort by field. | "sales" |
data.sort.direction | string | Sort direction. | "desc" |
data.use_with_other | int | Whether the coupon can be used with other discounts. | 0 |
data.prerequisite_customer_ids | array | List of prerequisite customer IDs. | [] |
data.prerequisite_customer_segment_ids | array | List of prerequisite customer segment IDs. | [] |
data.config.banner_url | string | URL for the coupon banner. | "" |
data.config.banner_size | string | Size of the coupon banner. | "" |
data.config.count_down.show_count_down | boolean | Whether to show a countdown for the coupon. | false |
data.config.count_down.format | string | Countdown format. | "" |
data.allocation_method | string | Allocation method for the coupon. | "" |
data.tips.msg | string | Tips message for the coupon. | "" |
data.only_valid_first_order_customer | boolean | Whether the coupon is only valid for the first order. | 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 | |
422 | Title cannot be blank. | Empty title. | Title cannot be blank. |
Value Type is invalid. | The type value provided is invalid. | Value Type is invalid. | |
Value Type cannot be blank. | Empty value type | Value Type cannot be blank. | |
Target Selection is invalid. | The target selection provided is invalid. | Target Selection is invalid. | |
Target Type is invalid. | The target type provided is invalid. | Target Type is invalid. |