🔒
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

📘
Public Request Parameters

Body Parameters

Parameter	Type	Required	Description	Example
`price_rule`	object	Yes	The price rule configuration object	`{...}`

Price Rule Object Structure

Parameter	Type	Required	Description	Example
`title`	string	Yes	Name of the price rule	`Summer Sale 2023`
`value`	float	Yes	Discount value amount	`10.0`
`value_type`	string	Yes	Type of discount value (fixed_amount, percentage)	`percentage`
`usage_limit`	int32	No	Maximum number of times the rule can be used	`100`
`allocation_limit`	int32	No	Limit of discount allocation	`1`
`once_per_customer`	int32	No	Whether the rule applies once per customer (1=yes, 0=no)	`1`
`prerequisite`	int32	No	Prerequisite condition flag	`0`
`target_selection`	string	Yes	Target selection method (all, prism, explicit)	`all`
`target_type`	string	Yes	Type of target (line_item, shipping_line)	`line_item`
`starts_at`	string	Yes	Start date of the price rule (Format: YYYY-MM-DDTHH:mm:ssZ)	`2023-06-01T00:00:00Z`
`ends_at`	string	Yes	End date of the price rule (Format: YYYY-MM-DDTHH:mm:ssZ)	`2023-06-30T23:59:59Z`
`entitled_product_ids`	array of strings	No	List of entitled product IDs	`["prod_123", "prod_456"]`
`entitled_variant_ids`	array of strings	No	List of entitled variant IDs	`["var_123", "var_456"]`
`entitled_collection_ids`	array of strings	No	List of entitled collection IDs	`["coll_123", "coll_456"]`
`prerequisite_subtotal_range`	array of objects	No	Prerequisite subtotal range conditions	`[ {...} ]`
`prerequisite_quantity_range`	array of objects	No	Prerequisite quantity range conditions	`[ {...} ]`

Prerequisite Subtotal Range Object Structure

Parameter	Type	Required	Description	Example
`greater_than_or_equal_to`	string	No	Minimum subtotal amount	`100.0`
`value`	string	No	Subtotal value	`100.0`
`value_percentage`	string	No	Subtotal percentage value	`10.0`
`value_event_type`	string	No	Event type for value calculation	`purchase`
`value_condition`	string	No	Condition for value comparison	`greater_than`
`target_type`	string	No	Target type for value	`line_item`
`target_data`	array of strings	No	Target data for value	`["prod_123"]`

Prerequisite Quantity Range Object Structure

Parameter	Type	Required	Description	Example
`greater_than_or_equal_to`	string	No	Minimum quantity	`5`
`value`	string	No	Quantity value	`5`
`value_percentage`	string	No	Quantity percentage value	`10.0`
`value_event_type`	string	No	Event type for quantity	`purchase`
`value_condition`	string	No	Condition for quantity comparison	`greater_than`
`target_type`	string	No	Target type for quantity	`line_item`
`target_data`	array of strings	No	Target data for quantity	`["prod_123"]`

Response Explanation

Public Response Parameters

📘
Public Response Parameters

Successful Response

Parameter	Type	Example	Description
`code`	string	`200`	Error code (200 indicates success)
`message`	string	`Success`	Error message
`data`	object	`{...}`	Contains the price rules data
`data.price_rule`	object	`{...}`	price rule object

Price Rule Object Structure

Parameter	Type	Example	Description
`id`	string	`pr_123456`	Unique identifier of the price rule
`title`	string	`Summer Sale`	Name of the price rule
`value`	float	`10.0`	Discount value amount
`value_type`	string	`fixed_amount`	Type of discount value (fixed_amount, percentage)
`usage_limit`	int32	`100`	Maximum number of times the rule can be used
`times_used`	int32	`45`	Number of times the rule has been used
`allocation_method`	string	`each`	How the discount is allocated (each, across)
`allocation_limit`	int32	`1`	Limit of discount allocation
`allocation_limit_amount`	float	`5.0`	Maximum amount for allocation limit
`once_per_customer`	int32	`1`	Whether the rule applies once per customer (1=yes, 0=no)
`prerequisite`	int32	`0`	Prerequisite condition flag
`customer_selection`	string	`all`	Customer selection method (all, prism, explicit)
`target_selection`	string	`all`	Target selection method (all, prism, explicit)
`target_type`	string	`line_item`	Type of target (line_item, shipping_line)
`target_price_type`	string	`original`	Price type target (original, current)
`created_at`	string	`2023-06-20T15:30:00Z`	Timestamp when the price rule was created
`updated_at`	string	`2023-06-21T09:15:00Z`	Timestamp when the price rule was last updated
`starts_at`	string	`2023-06-01T00:00:00Z`	Start date of the price rule
`ends_at`	string	`2023-06-30T23:59:59Z`	End date of the price rule
`prerequisite_customer_ids`	array of strings	`["cust_123", "cust_456"]`	List of prerequisite customer IDs
`prerequisite_customer_segment_ids`	array of strings	`["seg_123", "seg_456"]`	List of prerequisite customer segment IDs
`entitled_product_ids`	array of strings	`["prod_123", "prod_456"]`	List of entitled product IDs
`entitled_variant_ids`	array of strings	`["var_123", "var_456"]`	List of entitled variant IDs
`entitled_filter_ids`	array of strings	`["flt_123", "flt_456"]`	List of entitled filter IDs
`entitled_filter_list`	array of strings	`["filter1", "filter2"]`	List of entitled filter list items
`variant_product_ids`	array of strings	`["prod_123", "prod_456"]`	List of variant product IDs
`entitled_collection_ids`	array of strings	`["coll_123", "coll_456"]`	List of entitled collection IDs
`entitled_area_list`	array of strings	`["area1", "area2"]`	List of entitled area list items
`prerequisite_subtotal_range`	array of objects	`[ {...} ]`	Prerequisite subtotal range conditions
`prerequisite_quantity_range`	array of objects	`[ {...} ]`	Prerequisite quantity range conditions

Error Response

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

API Structure Overview