🔒
Requires price_rules access scope. More access scope

The Price Rule List API retrieves a list of price rules that can be applied to customer orders.

This API is especially useful for:

Fetching all active and inactive price rules in your store.
Filtering price rules by specific criteria such as start date, end date, or usage count.
Retrieving detailed configurations of discount rules for analysis or updates.

Request Parameters

Public Request Parameters

📘
Public Request Parameters

Query Parameters

Parameter	Type	Required	Description	Example
`cursor`	string	No	Cursor for pagination, use the cursor from the response to retrieve the next page	`cursor_123456`
`page_size`	int32	No	A limit on the number of objects to be returned. Ranges from 1 to 250. Default is 50	`20`
`starts_at_min`	string	No	Minimum timestamp for filtering price rules by start date. Format: YYYY-MM-DDTHH:mm:ssZ	`2023-01-01T00:00:00Z`
`starts_at_max`	string	No	Maximum timestamp for filtering price rules by start date. Format: YYYY-MM-DDTHH:mm:ssZ	`2023-12-31T23:59:59Z`
`ends_at_min`	string	No	Minimum timestamp for filtering price rules by end date. Format: YYYY-MM-DDTHH:mm:ssZ	`2023-01-01T00:00:00Z`
`ends_at_max`	string	No	Maximum timestamp for filtering price rules by end date. Format: YYYY-MM-DDTHH:mm:ssZ	`2023-12-31T23:59:59Z`
`times_used`	int32	No	Filter price rules by number of times used	`10`

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_rules`	array of objects	`[ {...}, {...} ]`	List of price rule objects
`data.cursor`	string	`cursor_123456`	Cursor for pagination
`data.has_more`	boolean	`true`	Indicates if there are more results available

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

Prerequisite Subtotal Range Object Structure

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

Prerequisite Quantity Range Object Structure

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

Error Response

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

API Structure Overview