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:
id
The rule's identifier (we recommend using UUIDs, if not specified will be automatically generated and added by the Core API integration).
"abcd-1234-xyzk-5678"
name
The rule's name (we recommend adding all essential information to help easily identify it among others).
"10% discount on tagged orders"
priority
The order in which the rules are evaluated (the lower the number, the higher the priority).
2
conditions_logic
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
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.
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.
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": "[email protected]",
"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
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": "[email protected]",
"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 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": "[email protected]",
"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" }
}
]
}
}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": "[email protected]",
"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" }
}
]
}
}Keep reading to learn more about how to set conditions and actions for a a rule or feel free to browse the use cases section to check more examples of rules based on real ecommerce scenarios.
Last updated