Skip to main content
Version: 1.0.0

Rule Promotions API

Rule Promotions provide the flexibility to offer diverse discounts to shoppers. This functionality supports discounts of varying complexities, from code-based customer discounts, to "Buy X Get Y" scenarios, fixed price promotions, and more based on your business needs.

You can create a Rule Promotion using the Rule Promotions API or through the Promotions Builder in Commerce Manager.

To apply Rule Promotions in carts and orders across an entire store, please enable the use_rule_promotions configuration in Cart Settings. You can also update a specific cart to use Rule Promotions by updating the cart's specific discount settings. Please see Update A Cart for more details.

Enabling Rule Promotions enacts Hybrid Mode, allowing simultaneous use of both Promotions Standard and Rule Promotions discounts.

For example, let's say a store provides the following promotions:

  • A Promotions Standard discount for 10% off the shopping cart
  • A Rule Promotion offering for a 20% discount on the shopping cart

If a cart qualifies for both discounts based on the respective eligibility criteria, the system applies both types of discounts to the shopping cart, starting with Promotions Standard definitions before applying Rule Promotions. In this case, the application results in a 10% discount from the Promotions Standard definition and a 20% discount from the Rule Promotion.

Rule Set​

A rule set is the criteria that determine when and how promotions get applied. Rule Sets consist of rule conditions and corresponding actions, which define eligibility and application details, respectively. Rule Sets may also contain targeted catalogs and currencies for further application granularity.

Example Buy an apple, get an orange 50% off.

Here, buying an apple is the rule and the 50% discount on an orange is the action.

Rules​

Rules describe the conditions necessary for promotion eligibility.

In our apple-orange example above, the rule indicates the shopper must buy an apple to get the discount on an orange. In other words, the buying of an apple is the condition which determines eligibility for the corresponding discount.

Actions​

Actions describe how discounts apply to eligible carts and orders. These signify the discount type, level, configurations, and any limitations or restrictions when applying.

Actions can also include:

  • Action conditions: specify which items should be included or excluded when applying the discounts. These can be based on factors such as item SKUs, product attributes, quantities, or categories.
  • Action limitations: impose restrictions on the number of products eligible for discounts, maximum discount amounts, and/or total applications for discounts.

In the apple-orange example, the action denotes the system applies a 50% discount to an orange, assuming the eligibility rules are met. For more complex scenarios, the action might say to provide a 50% discount on up to three oranges or might provide a fixed $1 discount on the two most expensive items from the "fruit" category.

note

For promotions that include a mix of item and cart rules or actions, we recommend including the specific item conditions in all item strategies to ensure desired discount applications.

For complex promotions in general, we recommend including specific item conditions on all item strategies to ensure the appropriate items receive discounts. Please see the Promotions Builder How-To for more details on specifying conditions, restrictions, and inclusions.

Action Limitations​

Action limitations restrict how a promotion is applied and can be combined with action conditions to create specific discount rules. The following limitations are available:

  • Maximum Discount (max_discount): Specifies the maximum total discount amount that can be applied. This applies to Cart Percent and Item Percent discount promotions.
  • Maximum Quantity (max_quantity): Limits the number of units per eligible item that can receive the promotion. This applies to Item Discount promotions.
  • Items Limitation (items): Applies only to Item Fixed and Item Percent discount promotions. It determines which items in the cart are eligible for the discount:
    • max_items: Specifies the maximum number of items eligible for the discount.
    • price_strategy: Determines how eligible items are selected based on price:
      • Cheapest (default): The discount is applied to the cheapest item(s) in the cart.
      • Expensive: The discount applies to the most expensive item(s) in the cart.

These limitations can be used independently or combined to create granular discount applications.

For example, consider a 50% discount on items from a category, with the following limitations:

  • Applies to a maximum of two items (max_items: 2)
  • Only applies to the two cheapest eligible items (price_strategy: cheapest)
  • Limits the total discount to $10 (max_discount: 1000)
  • Ensures a maximum of two units per eligible item receive the discount (max_quantity: 2)

This structure allows promotions to be precisely controlled to match business requirements while maintaining flexibility in promotional rules.

For more details, see the Action Limitations Overview.

Catalogs and Currencies​

As part of the Rule Set, you can also specify the catalogs and currencies for a given Rule Promotion.

With catalogs defined, the promotion only considers items from the identified catalogs and therefore will not consider custom items or items from other catalogs. With no catalogs defined, the promotion considers all items, including custom items.

Specifying a currency for the Rule Promotion restricts the promotion to carts of that currency. Notably, you can only set one currency per Rule Promotion.

Building Blocks​

Strategies​

Strategies describe the types of condition criteria or application actions used to build a promotion. A given promotion can be comprised of several strategies in its rules and actions. These might include several instances of similar strategies, different strategies, or some combination thereof. Think of these as building blocks that can be applied together to provide a functional discount.

  • Rule strategies define the types of conditions that need to be met for eligibility. These might include cart total amount, item prices, cart custom attributes, and more.
  • Action strategies refer to the type of action execution run when the eligibility criteria are met. For actions, the possible strategies are cart_discount and item_discount. For more information, please see Promotions Builder API Overview.

Operators and Args​

Operators determine how to evaluate a given strategy, while args define the value threshold to measure against. For example, please consider the following condition strategy:

{
  "strategy": "cart_total",
  "operator": "gte",
  "args": [ 10000 ]
}

In this example, the strategy is cart_total, telling the system to assess eligibility based on the total cart value. The operator is a greater-than-or-equal-to (gte) evaluation, indicating the candidate value (in this case, cart total) becomes eligible once it reaches or exceeds the threshold. Finally, the args value provides the threshold value to compare against, 10000. Taken together, then, this strategy looks for cart totals greater than or equal to 10000.

Please note: different strategies support different operators. For more information, please see Rule Promotions API Overview.

Children and Sub-Conditions​

For additional promotion granularity, some strategies support additional specifications via children and condition fields. These fields contain strategies, which provide further specifications around their parent strategy evaluations.
In other words, sub-conditions refer to additional criteria or conditions that must be met for a particular promotion to be applied.

The following strategies support children/sub-conditions:

  • item_price
  • item_quantity
  • item_category
  • item_attribute
  • and
  • or

Notably, when multiple sub-condition siblings exist, they are combined together, such that all sub-conditions must be met to fulfill eligibility.

Stacking​

Promotion stacking and priority are key elements in managing discounts, ensuring promotions are applied as intended. Stacking allows multiple promotions to be applied to a single cart, either targeting the same items or different ones. The stackable flag determines whether a promotion can stack with others, defaulting to true. If set to false, no other promotion can stack on top, and the highest-priority promotion takes precedence.

Priority settings dictate the order in which promotions are applied, with higher numbers indicating higher priorities. By default, promotions without assigned priorities are applied in reverse order of creation, with newer promotions applied first and calculated against any existing discounted prices.

Hybrid Mode enables the coexistence of Standard Promotions and those configured in the Promotions Builder, with each functioning independently. This means Standard Promotions can stack alongside non-stackable Builder promotions, and their stackability and priority settings remain unaffected by Standard Promotions.

Override stacking, set using the override_stacking flag, provides an additional layer of control over how promotions interact. This flag determines whether the promotion can stack with other promotions that are typically non-stackable and defaults to false when not set. When set to true, the promotion can stack with promotions configured as non-stackable, unless those non-stackable promotions also override stacking.

Shipping​

Rule Promotions support shipping discounts, identified by the corresponding strategies during promotion creation. Shipping discounts apply to shipping group base prices and do not impact shipping taxes or configured shipping fees. Please see Shipping Groups for more information on creating and interacting with shipping groups.

Authentication​

Security Scheme Type:

http

HTTP Authorization Scheme:

bearer

Contact

Elastic Path:

URL: https://elasticpath.com

License

MIT