Create Price Rule

🔒

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:

  1. Managing discounts and promotional campaigns.
  2. Creating conditional offers based on cart total or product quantity.
  3. Automating discount rules for specific products or product variants.

Request Parameters

Public Request Parameters

📘

Public Request Parameters

Body Parameters

FieldTypeRequiredDescriptionExample
titlestringYesTitle of this price rule."Discount Rule Title"
valuedoubleYesValue for this discount.50.25
value_typestringYesDiscount type. Options: fixed_amount for a fixed discount, or percentage for a percentage discount."fixed_amount"
usage_limitint32NoThe usage limit. -1 means no limit.-1
allocation_limitint32NoRedeem count limit per checkout: 0 means only one redeem allowed, 999 means no limit.0
once_per_customerint32NoMaximum usage per customer. -1 or 0 means no limit.1
prerequisiteint32NoIndicates if this discount has prerequisites. 1 means yes, 0 means no.1
target_selectionstringYesTarget products allowed for this discount. Options: all for all products, entitled for specific products."entitled"
target_typestringNoTarget type of this discount."line_item"
starts_atstringYesStart time of the discount."2024-12-01T00:00:00Z"
ends_atstringYesEnd time of the discount."2024-12-31T23:59:59Z"
entitled_product_idsarray[string]NoSpecifies 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_idsarray[string]NoSpecifies the product variant IDs allowed for the price rule.["ce21d85-a419-4d4e-a17d-5bddbc4ab7f6"]
prerequisite_subtotal_rangearray[object]NoPrerequisite for total amount in the cart.[{"greater_than_or_equal_to":"100","value":"10"}]
prerequisite_subtotal_range.greater_than_or_equal_tostringYesSpecifies the minimum total cart amount required."100"
prerequisite_subtotal_range.valuestringYesValue used for discount application."10"
prerequisite_subtotal_range.target_typestringNoSpecifies the type of target the rule applies to.""
prerequisite_subtotal_range.target_dataarray[string]NoSpecifies IDs of specific target items for the rule.[]
prerequisite_quantity_rangearray[object]NoPrerequisite for total quantity of products in the cart.[{"greater_than_or_equal_to":"5","value":"20"}]
prerequisite_quantity_range.greater_than_or_equal_tostringYesSpecifies the minimum total product quantity required."5"
prerequisite_quantity_range.valuestringYesValue used for discount application."20"
prerequisite_quantity_range.target_typestringNoSpecifies the type of target the rule applies to.""
prerequisite_quantity_range.target_dataarray[string]NoSpecifies IDs of specific target items for the rule.[]

Response Explanation

Public Response Parameters

📘

Public Response Parameters

Successful Response

FieldTypeDescriptionExample
pageintCurrent page number in the response.0
limitintNumber of items per page.10
totalintTotal number of coupons.2
dataarrayList of coupon objects.[ ... ]
data.idstringUnique identifier for the coupon."202314454241654711"
data.store_idintID of the store associated with the coupon.11218
data.life_cycle_typestringLifecycle type of the coupon."begin_end"
data.survival_timeintSurvival time of the coupon in seconds.86400
data.starts_atintStart time of the coupon (Unix timestamp).1673246985
data.ends_atintEnd time of the coupon (-1 indicates no end time).-1
data.statusintInternal 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_typestringType of discount."percentage"
data.value_typestringValue type of the discount."percentage"
data.valuestringDiscount value."10"
data.usage_limitintLimit on the number of times the coupon can be used (-1 for unlimited).-1
data.once_per_customerintWhether the coupon can only be used once per customer.0
data.titlestringTitle of the coupon."coupon1"
data.stockintCurrent stock of the coupon.0
data.codestringCode of the coupon.""
data.prerequisiteintPrerequisite value for the coupon.0
data.is_admin_showintWhether the coupon is visible to the admin.0
data.target_selectionstringTarget selection for the coupon."all"
data.progressstringCurrent progress of the coupon."ongoing"
data.using_statestringCurrent state of coupon usage.""
data.allocation_limit_amountstringAllocation limit amount for the coupon."0"
data.entitled_area_listarrayList of entitled areas for the coupon.[]
data.prerequisite_quantity_rangearrayPrerequisite quantity range for the coupon.[ ... ]
data.prerequisite_subtotal_rangearrayPrerequisite subtotal range for the coupon.[ ... ]
data.entitled_product_idsarrayList of entitled product IDs.[]
data.entitled_variant_idsarrayList of entitled variant IDs.[]
data.entitled_sortarraySort criteria for entitled items.[]
data.times_usedintNumber of times the coupon has been used.1
data.sort.bystringSort by field."sales"
data.sort.directionstringSort direction."desc"
data.use_with_otherintWhether the coupon can be used with other discounts.0
data.prerequisite_customer_idsarrayList of prerequisite customer IDs.[]
data.prerequisite_customer_segment_idsarrayList of prerequisite customer segment IDs.[]
data.config.banner_urlstringURL for the coupon banner.""
data.config.banner_sizestringSize of the coupon banner.""
data.config.count_down.show_count_downbooleanWhether to show a countdown for the coupon.false
data.config.count_down.formatstringCountdown format.""
data.allocation_methodstringAllocation method for the coupon.""
data.tips.msgstringTips message for the coupon.""
data.only_valid_first_order_customerbooleanWhether 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.

FieldTypeExampleDescription
errorsArray[ "invalid line_item id"]A list of errors encountered during the request processing.
FieldTypeExampleDescription
errorString "store is not active"Indicates an error encountered during the process

Error Detail

Status CodeMessagePossible ReasonExample Response
400Bad RequestInvalid input format or request structure (e.g., missing required fields or incorrect data types).Bad Request
UnauthorizedThe request is missing valid authentication credentials or the credentials provided are invalid.Unauthorized
422Title 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 typeValue 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.

API Structure Overview

Language
Credentials
Header
URL
Click Try It! to start a request and see the response here!