Need to create rules based on bundles?
Learn more
LogoLogo
APIsChangelog
  • Getting started
  • Rules
  • Conditions
    • Scope
    • Aggregations
    • Nested
    • Dynamic values
  • Actions
    • Types
      • Percentage
      • Fixed amount
      • Fixed price
      • Buy X pay Y
      • Every X discount Y
    • Bundle
      • Balanced
      • Every
    • Aggregation
    • Limit
  • Matchers
  • Operators
  • Check and validation
  • Core API integration
    • Order rules
    • Price rules
    • Virtual relationships
  • Resources
    • Promotions
    • Price lists
  • Use cases
    • Promotions
      • Discount line items based on item's price
      • Get a discount when paying by credit card
      • Discount an order based on promo item and total number of items
      • Offer a specific shipping method for free in a specific country
      • Discount items with large stock availability
      • Discount all the SKU in an order based on the shipping country
      • Discount all the SKU in an order based on the customer email domain
    • Price lists
      • Discount all prices greater than or equal to a specific value
      • Discount specific SKUs for new clients
      • Change strike-through price based on customer email domain
On this page
  • Example
  • All rules match
  • Only the first rule matches
  • Only the second rule matches
  • No rules match

Rules

How rules are structured and what are the required and optional parameters to define a rule

Rules are defined within a JSON payload as an array of rule objects under the rules key. For each rule you must provide at least name, one or more conditions that have to be satisfied for the rule to match, and one or more actions that will be applied if the conditions are met:

{
  "rules": [
    {
      "name": "First rule",
      ...
      "conditions": [
        { ... },
        { ... }
      ],
      "actions": [
        { ... },
        { ... },
        { ... }
      ]
    },
    {
      "name": "Second rule",
      ...
      "conditions": [
        { ... },
        { ... },
        { ... }
      ],
      "actions": [
        { ... },
        { ... }
      ]
    },
    { ... }
  ]
}

Other optional rule's parameters (such as a unique identifier and the logic that you want to use to evaluate multiple rules) can be also specified:

Key
Type
Required
Description
Example

id

String

"abcd-1234-xyzk-5678"

name

String

The rule's name (we recommend adding all essential information to help easily identify it among others).

"10% discount on tagged orders"

priority

Integer

The order in which the rules are evaluated (the lower the number, the higher the priority).

2

conditions_logic

String

The logic according to which the conditions are evaluated to determine the overall match. Can be one of and or or, default is and.

or

conditions

Array

The conditions that must be satisfied for the rule to match.

actions

Array

The actions that will be applied if the conditions are met.

In case of multiple rules, all and only the actions belonging to the matching rules will be applied. If no priority is defined, the rules are applied in the order that they are listed in the rules array (starting from priority 0).

For performance reasons, the maximum number of rules within a rules payload is 10.

Example

Let's consider a combination of rules that implements a quite complex promotional logic. Based on the order payload checked against them the rules application may result in different outcomes. Some of them are analyzed here below.

  1. The first rule contains two conditions and one action to apply a 2500 cents discount per unit to all the products in the order that costs more than 9900 cents if the order contains such kind of products and the total order's amount is at least 50000 cents.

  2. The second rule contains one condition and two actions to apply an additional 15% discount on all the products in the order and offer free shipping if the email address of the customer who placed the order belongs to a specified domain.

{
  "rules": [
    {
      "name": "Get 2500 cents off item cost based on items price or order total amount",
      "conditions": [
        {
          "field": "order.line_items.unit_amount_cents",
          "matcher": "gt",
          "value": 9900,
          "group": "discountable-items"
        },
        {
          "field": "order.total_amount_cents",
          "matcher": "gteq",
          "value": 50000
        }
      ],
      "actions": [
        {
          "type": "fixed_amount",
          "value": 2500,
          "selector": "order.line_items.sku",
          "groups": [ "discountable-items" ]
        }
      ]
    },
    {
      "name": "Get 15% off item cost plus free shipping for company customers",
      "conditions": [
        {
          "field": "order.customer_email",
          "matcher": "matches",
          "value": ".*@mybrand.com"
        }
      ],
      "actions": [
        {
          "type": "percentage",
          "selector": "order.line_items.sku",
          "value": 0.15
        },
        {
          "type": "percentage",
          "selector": "order.line_items.shipment",
          "value": 1
        }
      ]
    }
  ]
}

All rules match

This order contains at least one SKU that costs more than 9900 cents, the order total amount is greater than or equal to 50000 cents, and the associated customer email matches the specified domain:

{
  "order": {
    "id": "oXkhYLlzgE",
    "customer_email": "john@mybrand.com",
    "total_amount_cents": 66000,
    "line_items": [
      {
        "id": "dKdhYLlzgE",
        "quantity": 1,
        "unit_amount_cents": 15000,
        "sku": { "id": "dKfhgdlzgE" }
      },
      {
        "id": "eKfhYFkztQ",
        "quantity": 2,
        "unit_amount_cents": 5000,
        "sku": { "id": "sDfhYFkcfR" }
      },
      {
        "id": "kKffYAkzdW",
        "quantity": 2,
        "unit_amount_cents": 20000,
        "sku": { "id": "sWfhYDccwQ" }
      },
      {
        "id": "adfSYwAzar",
        "quantity": 1,
        "unit_amount_cents": 1000,
        "shipment": { "id": "dwFhYDGtwE" }
      }
    ]
  }
}

Both rules match and all the three actions will be applied, meaning that:

  • The identified discountable items will be discounted by 2500 cents per unit based on the first rule. An additional 15% discount due to the second rule will be also applied to those items.

  • All the other line items in the order associated with an SKU (if any) will be discounted by 15%.

  • All the shipment costs will be zeroed by applying a 100% percentage discount.

[
  {
    "id": "g2584766-ca17-4666-90b6-866a115bacgd",
    "name": "Get 2500 cents off item cost based on items price or order total amount",
    "priority": 0,
    "match": true,
    "conditions_logic": "and",
    "conditions": [
      {
        "field": "order.line_items.unit_amount_cents",
        "matcher": "gt",
        "value": 9900,
        "group": "discountable-items",
        "match": true,
        "matches": [
          {
            "order": "oXkhYLlzgE",
            "line_item": "dKdhYLlzgE",
            "group": "discountable-items"
          },
          {
            "order": "oXkhYLlzgE",
            "line_item": "kKffYAkzdW",
            "group": "discountable-items"
          }
        ],
        "scope": "any"
      },
      {
        "field": "order.total_amount_cents",
        "matcher": "gteq",
        "value": 50000,
        "group": "1cd66bb2-56d9-44ac-805d-33d29d56fe40",
        "match": true,
        "matches": [ 
          { 
            "order": "oXkhYLlzgE",
            "group": "1cd66bb2-56d9-44ac-805d-33d29d56fe40"
          } 
        ],
        "scope": "any"
      }
    ],
    "actions": [
      {
        "resources": [
          {
            "resource_type": "line_items",
            "id": "dKdhYLlzgE",
            "group": "discountable-items",
            "quantity": 1,
            "value": 2500,
            "action_type": "fixed_amount"
          },
          {
            "resource_type": "line_items",
            "id": "kKffYAkzdW",
            "group": "discountable-items",
            "quantity": 2,
            "value": 2500,
            "action_type": "fixed_amount"
          }
        ]
      }
    ]
  },
  {
    "id": "a1234567-ce16-3234-90k2-566a465bachy",
    "name": "Get 15% off item cost plus free shipping for company customers",
    "priority": 1,
    "match": true,
    "conditions_logic": "and",
    "conditions": [
      {
        "field": "order.customer_email",
        "matcher": "matches",
        "value": ".*@mybrand.com",
        "group": "1cd66bb2-56d9-44ac-805d-33d29d56fe40
        "match": true,
        "matches": [
          { 
            "order": "oXkhYLlzgE",
            "group": "1cd66bb2-56d9-44ac-805d-33d29d56fe40"
          }
        ],
        "scope": "any"
      }
    ],
    "actions": [
      {
        "resources": [
          {
            "resource_type": "line_items",
            "id": "dKdhYLlzgE",
            "group": "1cd66bb2-56d9-44ac-805d-33d29d56fe40",
            "quantity": 1,
            "value": 0.15,
            "action_type": "percentage"
          },
          {
            "resource_type": "line_items",
            "id": "eKfhYFkztQ",
            "group": "1cd66bb2-56d9-44ac-805d-33d29d56fe40",
            "quantity": 2,
            "value": 0.15,
            "action_type": "percentage"
          },
          {
            "resource_type": "line_items",
            "id": "kKffYAkzdW",
            "group": "1cd66bb2-56d9-44ac-805d-33d29d56fe40",
            "quantity": 2,
            "value": 0.15,
            "action_type": "percentage"
          }
        ]
      },
      {
        "resources": [
          {
            "resource_type": "line_items",
            "id": "adfSYwAzar",
            "group": "1cd66bb2-56d9-44ac-805d-33d29d56fe40",
            "quantity": 1,
            "value": 1.0,
            "action_type": "percentage"
          }
        ]
      }
    ]
  }
]

As you can see, since no priority was defined at the rules level, the priority attribute in the results follows the default behavior and matches the order in which the rules are listed in the original rules payload.

Only the first rule matches

This order contains at least one SKU that costs more than 9900 cents, the order total amount is greater than or equal to 50000 cents, but the associated customer email doesn't match the specified domain:

{
  "order": {
    "id": "oXkhYLlzgE",
    "customer_email": "jane@yourbrand.com",
    "total_amount_cents": 66000,
    "line_items": [
      {
        "id": "dKdhYLlzgE",
        "quantity": 1,
        "unit_amount_cents": 15000,
        "sku": { "id": "dKfhgdlzgE" }
      },
      {
        "id": "eKfhYFkztQ",
        "quantity": 2,
        "unit_amount_cents": 5000,
        "sku": { "id": "sDfhYFkcfR" }
      },
      {
        "id": "kKffYAkzdW",
        "quantity": 2,
        "unit_amount_cents": 20000,
        "sku": { "id": "sWfhYDccwQ" }
      },
      {
        "id": "adfSYwAzar",
        "quantity": 1,
        "unit_amount_cents": 1000,
        "shipment": { "id": "dwFhYDGtwE" }
      }
    ]
  }
}

Only the first rule matches, meaning that:

  • The identified discountable items will be discounted by 2500 cents per unit.

  • No other additional discount will be applied.

[
  {
    "id": "g2584766-ca17-4666-90b6-866a115bacgd",
    "name": "Get 2500 cents off item cost based on items price or order total amount",
    "priority": 0,
    "match": true,
    "conditions_logic": "and",
    "conditions": [
      {
        "field": "order.line_items.unit_amount_cents",
        "matcher": "gt",
        "value": 9900,
        "group": "discountable-items",
        "match": true,
        "matches": [
          {
            "order": "oXkhYLlzgE",
            "line_item": "dKdhYLlzgE"
            "group": "discountable-items"
          },
          {
            "order": "oXkhYLlzgE",
            "line_item": "kKffYAkzdW"
            "group": "discountable-items"
          }
        ],
        "scope": "any"
      },
      {
        "field": "order.total_amount_cents",
        "matcher": "gteq",
        "value": 50000,
        "group": "0fe4c17c-fbf2-4418-9a28-0cd02e55916a",
        "match": true,
        "matches": [ 
          { 
            "order": "oXkhYLlzgE",
            "group": "0fe4c17c-fbf2-4418-9a28-0cd02e55916a" 
          } 
        ],
        "scope": "any"
      }
    ],
    "actions": [
      {
        "resources": [
          {
            "resource_type": "line_items",
            "id": "dKdhYLlzgE",
            "group": "discountable-items",
            "quantity": 1,
            "value": 2500,
            "action_type": "fixed_amount"
          },
          {
            "resource_type": "line_items",
            "id": "kKffYAkzdW",
            "group": "discountable-items",
            "quantity": 2,
            "value": 2500,
            "action_type": "fixed_amount"
          }
        ]
      }
    ]
  },
  {
    "id": "a1234567-ce16-3234-90k2-566a465bachy",
    "name": "Get 15% off item cost plus free shipping for company customers",
    "priority": 1,
    "match": false,
    "conditions_logic": "and",
    "conditions": [
      {
        "field": "order.customer_email",
        "matcher": "matches",
        "value": ".*@mybrand.com",
        "group": "0fe4c17c-fbf2-4418-9a28-0cd02e55916a",
        "match": false,
        "matches": [],
        "scope": "any"
      }
    ],
    "actions": []
  }
]

As you can see, the second rule's actions array is empty, which implies that the rule triggers no action since the related condition's matches array is empty (meaning that the condition is not satisfied).

Only the second rule matches

The customer email associated to this order matches the specified domain, the order contains at least one SKU that costs more than 9900 cents but the order total amount is lower than 50000 cents:

{
  "order": {
    "id": "oXkhYLlzgE",
    "customer_email": "john@mybrand.com",
    "total_amount_cents": 26000,
    "line_items": [
      {
        "id": "dKdhYLlzgE",
        "quantity": 1,
        "unit_amount_cents": 15000,
        "sku": { "id": "dKfhgdlzgE" }
      },
      {
        "id": "eKfhYFkztQ",
        "quantity": 2,
        "unit_amount_cents": 5000,
        "sku": { "id": "sDfhYFkcfR" }
      },
      {
        "id": "adfSYwAzar",
        "quantity": 1,
        "unit_amount_cents": 1000,
        "shipment": { "id": "dwFhYDGtwE" }
      }
    ]
  }
}

Only the second rule matches, meaning that:

  • All the line items in the order associated with an SKU will be discounted by 15%.

  • All the shipment costs will be zeroed by applying a 100% percentage discount.

[
  {
    "id": "g2584766-ca17-4666-90b6-866a115bacgd",
    "name": "Get 2500 cents off item cost based on items price or order total amount",
    "priority": 0,
    "match": false,
    "conditions_logic": "and",
    "conditions": [
      {
        "field": "order.line_items.unit_amount_cents",
        "matcher": "gt",
        "value": 9900,
        "group": "discountable-items",
        "match": true,
        "matches": [
          {
            "order": "oXkhYLlzgE",
            "line_item": "dKdhYLlzgE",
            "group": "discountable-items"
          }
        ],
        "scope": "any"
      },
      {
        "field": "order.total_amount_cents",
        "matcher": "gteq",
        "value": 50000,
        "group": "f8e14d34-08ee-4209-98b0-20b1755a3ece",
        "match": false,
        "matches": [],
        "scope": "any"
      }
    ],
    "actions": []
  },
  {
    "id": "a1234567-ce16-3234-90k2-566a465bachy",
    "name": "Get 15% off item cost plus free shipping for company customers",
    "priority": 1,
    "match": true,
    "conditions_logic": "and",
    "conditions": [
      {
        "field": "order.customer_email",
        "matcher": "matches",
        "value": ".*@mybrand.com",
        "group": "f8e14d34-08ee-4209-98b0-20b1755a3ece",
        "match": true,
        "matches": [
          { 
            "order": "oXkhYLlzgE",
            "group": "f8e14d34-08ee-4209-98b0-20b1755a3ece"
          }
        ],
        "scope": "any"
      }
    ],
    "actions": [
      {
        "resources": [
          {
            "resource_type": "line_items",
            "id": "dKdhYLlzgE",
            "group": "f8e14d34-08ee-4209-98b0-20b1755a3ece",
            "quantity": 1,
            "value": 0.15,
            "action_type": "percentage"
          },
          {
            "resource_type": "line_items",
            "id": "eKfhYFkztQ",
            "group": "f8e14d34-08ee-4209-98b0-20b1755a3ece",
            "quantity": 2,
            "value": 0.15,
            "action_type": "percentage"
          }
        ]
      },
      {
        "resources": [
          {
            "resource_type": "line_items",
            "id": "adfSYwAzar",
            "group": "f8e14d34-08ee-4209-98b0-20b1755a3ece",
            "quantity": 1,
            "value": 1.0,
            "action_type": "percentage"
          }
        ]
      }
    ]
  }
]

As you can see, the first rule's actions array is empty, which implies that the rule triggers no action since one of the related conditions' matches array is empty (meaning that the overall combination of conditions is not satisfied).

No rules match

The customer email associated with this order doesn't match the specified domain, the order total amount is greater than or equal to 50000 cents but the order doesn't contain at least one SKU that costs more than 9900 cents:

{
  "order": {
    "id": "oXkhYLlzgE",
    "customer_email": "jane@yourbrand.com",
    "total_amount_cents": 58000,
    "line_items": [
      {
        "id": "dKdhYLlzgE",
        "quantity": 5,
        "unit_amount_cents": 2000,
        "sku": { "id": "dKfhgdlzgE" }
      },
      {
        "id": "eKfhYFkztQ",
        "quantity": 4,
        "unit_amount_cents": 5000,
        "sku": { "id": "sDfhYFkcfR" }
      },
      {
        "id": "kKffYAkzdW",
        "quantity": 3,
        "unit_amount_cents": 9000,
        "sku": { "id": "sWfhYDccwQ" }
      },
      {
        "id": "adfSYwAzar",
        "quantity": 1,
        "unit_amount_cents": 1000,
        "shipment": { "id": "dwFhYDGtwE" }
      }
    ]
  }
}

None of the two rules matches, so no discount will be applied.

[
  {
    "id": "g2584766-ca17-4666-90b6-866a115bacgd",
    "name": "Get 2500 cents off item cost based on items price or order total amount",
    "priority": 0,
    "match": false,
    "conditions_logic": "and",
    "conditions": [
      {
        "field": "order.line_items.unit_amount_cents",
        "matcher": "gt",
        "value": 9900,
        "group": "discountable-items",
        "match": false,
        "matches": [],
        "scope": "any"
      },
      {
        "field": "order.total_amount_cents",
        "matcher": "gteq",
        "value": 50000,
        "group": "473aa43c-ae1e-4034-9a21-7cddd95b85ab",
        "match": true,
        "matches": [
          { 
            "order": "oXkhYLlzgE",
            "group": "473aa43c-ae1e-4034-9a21-7cddd95b85ab"
          }
        ],
        "scope": "any"
      }
    ],
    "actions": []
  },
  {
    "id": "a1234567-ce16-3234-90k2-566a465bachy",
    "name": "Get 15% off item cost plus free shipping for company customers",
    "priority": 1,
    "match": false,
    "conditions_logic": "and",
    "conditions": [
      {
        "field": "order.customer_email",
        "matcher": "matches",
        "value": ".*@mybrand.com",
        "group": "473aa43c-ae1e-4034-9a21-7cddd95b85ab",
        "match": false,
        "matches": [],
        "scope": "any"
      }
    ],
    "actions": []
  }
]

As you can see, both rules' actions array is empty, which implies that they trigger no action since the related conditions' matches arrays are empty (meaning that the conditions are not satisfied).

PreviousGetting startedNextConditions

Last updated 2 months ago

The rule's identifier (we recommend using , if not specified will be automatically generated and added by the ).

Learn more .

Learn more .

Keep reading to learn more about how to set and for a a rule or feel free to browse the section to check more examples of rules based on real ecommerce scenarios.

conditions
actions
use cases
Use cases
here
here
UUIDs
Core API integration