Skip to main content

Rule Promotions API Overview

The Rule Promotions Object

typestringRequiredSpecifies the type of the resource. The type of resource for this promotion is rule_promotion.
namestringRequiredSpecifies a name for the promotion.
descriptionstringRequiredSpecifies a description for the rule promotion.
enabledbooleanRequiredSpecifies whether the promotion is enabled. The options are true or false, and the default setting is false.
automaticbooleanOptionalSpecifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is false. When this value is set to true, a code is autogenerated. If this value is set to false, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.
startstringRequiredSpecifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format. For example, "start": "2000-01-01 12:00". If no time is specified, the default start and end time is set to 00:00.
endstringRequiredSpecifies the end date and time of the promotion or the end date of the promotion.

The rule_set Object

rule_set.catalog_idsstringOptionalSpecifies the catalogs that are eligible for the promotion. By default, the promotion applies to all items, including custom items. However, when rule_set.catalog_ids is defined, the promotion is only applied to items within the specified catalogs. If catalog IDs are specified, custom items cannot be applied as part of the promotion.
rule_set.currenciesstringOptionalSpecifies currencies that are applied for the promotion.
rule_set.rules.strategystringRequiredSpecifies strategies for the rule. Strategy decides how the rules are applied. The following strategies provide different criteria for applying rules, allowing for flexible and customizable promotion management:
  • cart_total: Considers the total value of items in the shopping cart.
  • cart_custom_attribute: Represents custom attributes associated with the entire shopping cart.
  • item_price: Indicates the price of individual items.
  • item_quantity: Considers the quantity of individual items.
  • item_sku: Pertains to specific item SKUs. Supports multiple SKUs separated by a comma. For example, [sku1,sku2].
  • item_category: Relates to item categories. Supports multiple unique identifiers of categories separated by a comma. For example, [cat1,cat2].
  • item_attribute: Involves item attributes, which include; Arguments: [productTemplate, field slug value, field type, field value]. For example, "Example: [template-1, brand, string, Adidas, Nike]". The maximum number of attribute values is 20.
  • item_product_id: Displays the product ID. It can be used for items without SKU, like skuless bundles. See Handling both Item SKU and Product ID together in Rule Promotion
When using these strategies, you can combine and or or as needed to specify the criteria. The and strategy is applied when multiple conditions must all be met. The or strategy is applied when at least one of the multiple conditions must be met.
rule_set.rules.childrenstring[array]OptionalSpecifies an array of rules within a rule set, particularly used when multiple rules are involved in defining a promotion. This structure allows for incorporating several rules within the same rule_set, where each rule establishes the criteria necessary for discount eligibility.

Additionally, you can include sub conditions within the rule_set.rules.childrento add additional criteria or conditions that must be met for a particular promotion to be applied. This is helpful for configuring complex promotions that require multiple, layered criteria. For configuring promotions with sub conditions, See Create a Cart Percent Discount with Sub Conditions and Create an Item Rule Promotion with Sub Condition.

rule_set.rules.operatorstringRequiredSpecifies the operators used for the rule strategy. The eq, gt,lt,gte, and lte operators are supported in the following rule strategies:
  • cart_total
  • item_price
  • item_quantity
The in and nin operators are supported in the following rule strategies:
  • item_sku
  • item_category
  • cart_custom_attribute
rule_set.rules.argsstring / numberRequiredRepresents the condition value associated with each rule within the rule set. The number of supported arguments varies based on the rule strategy:
  • For cart_total, item_price, and item_quantity strategies, only one argument is supported.
  • For item_sku and item_category strategies, the args field supports a minimum of 1 and a maximum of 400 arguments.

See Arguments

The actions object

rule_set.actions.strategystringRequiredDefines how the discount is applied. The available options are:
  • cart_discount
  • item_discount
rule_set.actions.argsstring/numberRequiredThe first argument specifies the format for the discount value. The available options are:
  • fixed
  • percent
  • fixed_price
The second argument indicates the value associated with the first argument. For example, ["percent", 20]. In the case of fixed_price, the second argument indicates the multiplier, for example, X for amount, and the third argument is the price. For example, ["fixed_price", 4, 100]. See Arguments
rule_set.actions.conditionobjectRequiredDefines how to apply discounts based on specified conditions. It supports multiple conditions and utilizes various strategies, operators, and arguments to determine when to apply the discount. See Create the Condition Rule Promotion.
  • Strategy specifies the condition strategy to be used. Available options include:
    • cart_total
    • item_price
    • item_quantity
    • item_sku
    • item_category
  • The and strategy is applied when multiple conditions must all be met.
  • Supported operators depend on the strategy used. For example:
    • eq, gt, lt, gte, and lte operators: Supported for item_price and item_quantity.
    • in and nin operators: Supported for item_sku, item_category, and other strategies.
  • Arguments for the condition are specified. This could be a single value or a list of values depending on the strategy and operator used. For example, for the item_quantity strategy with the gte operator, the argument [4] means that the condition is met if the quantity of the item is greater than or equal to 4.

Additionally, you can also include sub condition under actions object. A sub condition is an additional condition that further refines or restricts when the action associated with the rule should be executed. It provides more granularity and specificity to the rule, ensuring that the action is applied only under certain circumstances. See Create a Cart Percent Discount with Sub Conditions and Create an Item Rule Promotion with Sub Condition

rule_set.actions.limitationsobjectOptionalDefines how limitiations are applied to promotions. These limitations dictate how the promotion can be used and what criteria must be met for it to be applied. For more information, see Action Limitations.

Sample Response

"data": {
"type": "rule_promotion",
"id": "e42ec2df-5682-4047-bc22-9e5eb932ca4a",
"store_id": "85ea6cac-589a-4141-80d0-42b91aae73a7",
"name": "$5 off cart with custom attribute",
"description": "$5 off cart with custom attribute",
"enabled": true,
"automatic": true,
"rule_set": {
"catalog_ids": null,
"currencies": null,
"rules": {
"strategy": "cart_custom_attribute",
"operator": "in",
"args": [
"actions": [
"strategy": "cart_discount",
"args": [
"start": "2024-01-01T00:00:00Z",
"end": "2024-01-26T00:00:00Z",
"meta": {
"timestamps": {
"created_at": "2024-01-24T21:27:13.1Z",
"updated_at": "2024-01-24T21:27:13.1Z"