Raytail Promotion Interchange Format (RAYPIF)

1. Overview

1.1 Purpose

This document defines the Raytail Promotion Interchange Format (RAYPIF), a standardized JSON-based format for communicating promotion rules, conditions, and effects between systems in the Raytail Ecosystem. RAYPIF enables consistent promotion definition, validation, and execution across Point of Sale (POS), Cloud, e-commerce platforms, and other integrated business systems.

1.2 Scope

This specification covers:

• Core promotion metadata structure
• Rule definition syntax and semantics
• Effect specification formats
• Data binding and reference mechanisms
• Supported operations and comparison types
• Property definitions and data types

However, this does not aim to and WILL NOT define the promotion code structure, engine specifications or any other system specific implementation details (such as the possibility to apply multiple promotions per item). It just defines the communication format and definitions.

That being said it WILL give opinions and validations on what generally should happen and what validations are necessary where applicable.

1.3 Audience

This document is intended for:

• System architects designing the components relevant to the promotion engine
• Developers implementing the promotion logic or creation logic
• Integration engineers connecting disparate systems
• QA engineers validating the promotion behaviour
• Business analysts defining the promotion requirements

This document contains a lot of technical terms and as such is not very suitable for non-technical personnel, though they may be given access depending on the relevance an requirements.

1.4 Change log

2. Data Types

The format relies on JSON as the backing format and as such will support all the data types supported by the JSON specification. This section defines and constraints we put over the JSON data types.

2.1 Datetime

All date time should be provided in the ISO8601 specification format with timezone explicitly provided. You can use Z to indicate Zulu (UTC) time but timezone should always be provided.

2.2 Decimal types

All values provided as decimal values will be interpreted to have the following properties:

Effective Range

• Minimum: -999,999,999.999
• Maximum: 999,999,999.999
• Or equivalently: -999,999,999,999 to 999,999,999,999 (when all 12 digits are in the integer part)

Validation Examples:

Important Notes:

• Values exceeding precision of 12 should be rejected at validation time
• Leading zeros do not count toward precision (e.g., 000123.456 = precision of 6)
• Trailing zeros after the decimal point are significant (e.g., 100.000 uses scale of 3)

2.3 Integer types

All integer types must follow the following properties:

2.4 String types

The following applies to string types:

2.5 Collection Constraints

3. Root / Top-Level Structure

Every promotion will be defined at the top level as a JSON object with the following properties:

4. Image Object

This object defines the urls for the various files that can be used by the consuming applications.

5. Rule Node

There is no singular structure for a rule node. Instead there are a variety of them that could each have its own child/children. Look at the individual nodes for details on what could act as a root node and what could have multiple children.

Regardless of the node, each will have a property called type that will uniquely identify the node.

Look at the header area for a quote like the following for the configuration:

Type: the value to expect in the type property ChildType: the type of child nodes it could have (single, multiple, none or both) Root: true or false indicating if this could act as the root of the rules object TerminalNode: true or false indicating if this is a terminator / leaf node

5.1 Rule Logic Node

Combine various child nodes with logical operations.

Type: logic ChildType: multiple Root: true TerminalNode: false

It can have the following properties:

5.1.1 Supported Rule Logic Nodes

Below are all the supported logic nodes for RuleNodes. These are different to Effect logic nodes, try not to confuse them.

5.1.2 Examples

{
	"type": "logic",
	"subType": "and",
	"children": [
		RuleNode,
		...
	]
}

5.2 Resource Node

Specify the context for any subsequent node chain. For all supported resources and their fields check the Resources section.

Type: resource ChildType: single Root: true TerminalNode: false

It has no logic by itself and will evaluate to whatever the child evaluates to.

It can have the following properties:

5.2.1 Examples

5.2.1.1 Resource with actual identifier

{
	"type": "resource",
	"subType": "lineItem",
	"resource": "code_uom::10002326|EA",
	"groupChildren": true,
	"child": RuleNode,
}

5.2.1.2 Resource with reference

{
	"type": "resource",
	"subType": "lineItem",
	"resource": "ref::sourceArticle",
	"groupChildren": false,
	"child": RuleNode,
}

5.3 Comparison Node

A node that has two to three children and evaluates them based on mathematical or logical operators.

Type: comparison ChildType: multiple Root: true TerminalNode: false

It can have the following properties:

5.3.1 Supported Comparison Nodes

Below are all the supported nodes for ComparisonNodes.

5.3.2 Examples

{
	"type": "comparison",
	"subType": "neq",
	"children": [
		RuleNode,
		RuleNode
	]
}

5.4 Property Node

Extracts a property from the current resource context.

Type: property ChildType: none Root: false TerminalNode: true

It can have the following properties:

5.4.1 Examples

5.4.1.1 With actual property name and child

{
	"type": "property",
	"propertyName": "lineTotal"
}

5.4.1.2 With reference property and values

{
	"type": "property",
	"propertyName": "ref::propertyName",
	"convertEquivalent": false
}

5.5 Literal Node

Define constant values that can be used for comparison or for something like always true promotion.

Type: literal ChildType: none Root: true TerminalNode: true

It can have the following properties:

5.5.1 Supported Literal Nodes

Below are all the supported logic nodes for LiteralNodes.

5.5.2 Examples

{
	"type": "literal",
	"subType": "int",
	"value": "123"
}

5.6 Function Node

Some built in functions that allow you to tap into running state and other values.

Type: func ChildType: multiple or none Root: false TerminalNode: true (if no arguments) or false

It can have the following properties:

5.6.1 Supported Function Nodes

Below are all the supported sub types for Function Nodes.

5.6.2 Examples

5.6.2.1 Get current date time

{
	"type": "func",
	"function": "current_timestamp"
}

5.6.2.2 Trigger on every 200th transactions after 30th December 00:00 MDV time

{
	"type": "comparison",
	"subType": "eq",
	"children": [
		{
			"type": "func",
			"function": "mod",
			"children": [
				{
					"type": "func",
					"function": "sale_txn_count",
					"children": [
						{
							"type": "literal",
							"subType": "dateTime",
							"value": "2025-12-29T19:00:00.000+05:00"
						}
					]
				},
				{
					"type": "literal",
					"subType": "int",
					"value": "200"
				}
			]
		},
		{
			"type": "literal",
			"subType": "int",
			"value": "0"
		}
	]
}

5.7 Transformation Node

Transformation nodes change the output of a node (usually a PropertyNode) and modifies it so that we can have a workable version to be compared against.

Type: transform ChildType: single Root: false TerminalNode: false

It can have the following properties:

5.7.1 Transformation Object

Each transformation object defines the behaviour of the transform to apply.

They can have these properties:

The following are the possible values for on error.

• returnInput: returns input as is
• forwardInput: forwards the input as is to the next function
• returnDefault: returns the object in default
• forwardDefault: forwards the object in default
• stopExecution: this path and consequently this unique execution will be stopped. This does not mean the whole promotion is invalid, just the record being processed. For example: if we have 3 line items matching and the second one fails, 1 and 3 will still continue and can result in success.

5.7.2 Supported Transformations

Below are all the supported logic nodes for Function Nodes.

5.7.3 Local Variables

If any of the transformations provided to this node has saveLVar set, the value will be saved as a local variable specific to this transformation node. Meaning all subsequent transformations can access this value. They access this by providing lvar::<variable_name> to a parameter. The value will be attempted to be auto converted to the correct parameter type.

Example:

{
	"type": "comparison",
	"subType": "eq",
	"children": [
		{
			"type": "transform",
			"transformations": [
				{
					"transformation": "index_of",
					"params": ["fun"],
					"saveLVar": "index",
					"onError": "returnInput"
				},
				{
					"transformation": "substring",
					"params": ["lvar::index", "999"],
					"onError": "returnInput",
					"valueFrom": "__input__"
				}
			],
			"child": {
				"type": "literal",
				"subType": "string",
				"value": "transformations are fun"
			}
		},
		{
			"type": "literal",
			"subType": "string",
			"value": "fun"
		}
	]
}

will find the index of fun and take the remainder starting from there.

5.7.4 Transformation Process

The transformation is a powerful tool that follows the following process:

6. Effect Node

There is no singular structure for a effect node. Instead there are a variety of them that could each have its own child/children. Look at the individual nodes for details on what could act as a root node and what could have multiple children.

Regardless of the node, each will have a property called type that will uniquely identify the node.

Look at the header area for a quote like the following for the configuration:

Type: the value to expect in the type property ChildType: the type of child nodes it could have (single, multiple, none or both) Root: true or false indicating if this could act as the root of the effects object TerminalNode: true or false indicating if this is a terminator / leaf node

6.1 Effect Logic Node

Combine various child nodes with logical operations.

Type: logic ChildType: multiple Root: true TerminalNode: false

It can have the following properties:

6.1.1 Supported Effect Logic Nodes

Below are all the supported logic nodes for EffectNodes. These are different to Rule logic nodes, try not to confuse them.

6.2 Effect Discount Node

Provides a discount on items in the transaction.

Type: discount ChildType: none Root: true TerminalNode: true

It has the following properties:

6.2.1 Discount Context

Application of discounts assumes that the engine is aware of all the resources that contributed to the success of the ruleset. As such the triggering lineItems are expected to be in the context.

• If groupChildren is false then each matching item is assumed to be an independent context, applying discounts separately
• If groupChildren is true then the items that contributed to the grouping is considered part of the same context. This makes it very unlikely one line could participate in multiple contexts, but it is not impossible

Effects use this implicit context information:

• triggerOnly: Applies to items in the current context
• allMatching: Expands beyond context to all items matching resource filter

6.2.2 Discount Application Logic

Discount application can be broadly split into two ways defined by the subType parameter:

6.2.2.1 Header level (subType header)

When subType is header:

• Discount applies to entire transaction total
• resource and applyMechanism are ignored
• Based on applicationType:
  • If single: it is applied once
  • If stacking: it is applied once per context (up to <count>)

Example: VIP customers get 5% off entire transaction

{ 
	"type": "discount",
	"subType": "header",
	"conditionCode": "VIP_DISC",
	"value": 5.0,
	"isPercentage": true,
	"applicationType": "single"
}

Example: 50 MVR off per qualifying product group

{
	"type": "discount",
	"subType": "header",
	"conditionCode": "BULK_DISC",
	"value": 50.0,
	"isPercentage": false,
	"applicationType": "stacking:3"
}

If 3 product groups trigger independently, transaction gets 150 MVR off total

6.2.2.2 Line Item Level (subType lineItem)

When subType is lineItem, the application depends on applyMechanism and applicationType as the table below shows:

6.3 Free Item Node

Provides a free item as an effect.

Type: freeItem ChildType: none Root: true TerminalNode: true

It has the following properties:

Scaling Behavior:

• Each selector node in sourceQuantitySelector array is evaluated independently
• All resulting quantities are summed together to get the effective quantity
• triggerQuantity provides the baseline to match against
• Free item quantity = quantity × (total_from_all_selectors / triggerQuantity)
• Example: Buy 2 get 1 free. If customer buys 4, they get 2 free items.

Example with multiple selectors:

"sourceQuantitySelector": [
  {
    "type": "lineItem",
    "property": "quantity",
    "lookup": "code_uom::APPLE_JUICE|EA"
  },
  {
    "type": "lineItem",
    "property": "quantity",
    "lookup": "code_uom::ORANGE_JUICE|EA"
  }
]

If customer buys 3 apple juice + 2 orange juice = 5 total quantity With triggerQuantity: 2.0 and quantity: 1.0 Free items given = 1 × (5 / 2) = 2.5 → 2 free items (rounded down)

6.3.1 Source Selector Node

This is another family of nodes dedicated for selection of items to extract quantity from.

6.3.1.1 Header Selector Node

Selects a property from header.

Type: header Root: true TerminalNode: true

It can have the following properties:

6.3.1.2 Line Item Selector Node

Selects a property from line item.

Type: lineItem Root: true TerminalNode: true or false (in case of filter being given)

It can have the following properties:

6.3.1.3 Customer Selector Node

Selects a property from customer.

Type: customer Root: true TerminalNode: true or false (in case of filter being given)

It can have the following properties:

6.3.1.4 Tender Selector Node

Selects a property from tender.

Type: tender Root: true TerminalNode: true or false (in case of filter being given)

It can have the following properties:

6.3.1.5 Logic Selector Node

This is mostly the same as Rule Logic Node, with the change being that the children could only be Selector Nodes.

6.3.1.6 Comparison Selector Node

This is exactly the same as Rule Comparison Node, with the change being that the children could only be Selector Nodes.

6.3.1.7 Literal Selector Node

This is exactly the same as Rule Literal Node.

6.3.1.8 Property Selector Node

This is exactly the same as Rule Property Node.

6.3.1.9 Function Selector Node

This is exactly the same as Rule Function Node, with the change being that the children could only be Selector Nodes.

6.3.1.10 Transformation Selector Node

This is exactly the same as Rule Transformation Node, with the change being that the children could only be Selector Nodes.

7. Data Array

There might arise certain cases where you want to apply the same logic across multiple combinations of data. Usually this happens when you want to run something like a buy one get one free promotion across multiple articles all giving different free items for but with the same validity, promotion name and the such. Data array is here to help you with that. Each item in the data array is a unique application of the same rules.

7.1 Ref format

Most of the resource / value specific fields in both RuleNodes and EffectNodes support giving the value as ref::<fieldName> format. This indicates that the value should be taken from the data array with column name <fieldName>.

7.2 Structure

There is no defined structure for the data array object. Just the requirement that any ref:: field name should be present in every item within the array. If the fields ref::sourceItem and ref::targetItem are used in the promotion then the structure of each item should be:

{
	"sourceItem": "...",
	"targetItem": "..."
}

such that the object in root is:

{
	...
	"data": [
		{
			"sourceItem": "...",
			"targetItem": "..."
		},
		{
			"sourceItem": "...",
			"targetItem": "..."
		}
	]
	...
}

7.3 Error Handling

On creation side, validation should fail and it should not be possible to save without this field in the data array object. This is to prevent downstream from handling bad data.

However, downstream should also guard against this and log a warning about it and ignore the subbranch that has the problematic issue. If its part of the rules section then promotion should be discarded entirely as we may be providing benefits to transactions that does not meet the criteria.

8. Resources

The agreed upon resources that the specification will act upon are the following.

8.1 Resource Parameter

A subtree within the rules can have a ResourceNode with a resource parameter through which you can set the resource. The resource parameter needs a value to identify which resources match the pattern. For cases like line items, multiple rows could match it and will be evaluated one by one, separately.

The resource parameter will be in the format: <lookup_prefix>::<lookup_params> where the lookup params will be combined using pipe |. So for a 3 parameter lookup it will be <lookup_prefix>::<lookup_param1>|<lookup_param2>|<lookup_param3>.

8.1.1 Escape sequences

If any of the parameters have a pipe within its text, it should be escaped by adding a backslash \. If you need a backslash in the text it should likewise be escaped with a backslash. In the unlikely event that a backslash followed by a pipe is needed, the following is how it should look like: \\\|.

• \| results in |
• \\ results in \
• \\| results in \ with pipe splitting the params
• \\\| results in \|

8.1.2 Case sensitivity

When a parameter is evaluated, it should be checked ordinal with case ignored. So aBcD, ABCD, abcd, ... all should be considered the same.

8.2 Resource List

Below are the list of all resources available to a promotion.

8.2.1 Header

ResourceType: header

8.2.1.1 Resource lookups

There is only one header per transaction. So no matter what you give in the resource parameter, it will match.

8.2.1.2 Structure

Header is assumed to have the following fields:

8.2.2 Line Items

ResourceType: lineItem

8.2.2.1 Resource lookups

The following are the supported ways to lookup this resource.

8.2.2.1.1 Code with Uom

The article is matched with article code and uom.

Format: code_uom::<code>|<uom> Params:

• code: The article code. Should be an exact match
• uom: The unit of measure. Should be an exact match

8.2.2.1.2 Ean

The article is matched with the ean (barcode)

Format: ean::<ean> Params:

• ean: The article's barcode. Should be an exact match

8.2.2.1.3 Brand

The article is matched with the brand.

Format: brand::<brand> Params:

• brand: The article's brand. Should be evaluated in lowercase contains (%...% in sql)

8.2.2.1.4 Merchandising Category

The article is matched with the article's merchandising category.

Format: mc::<mc> Params:

• mc: The article's merchandising category. Should be evaluated in lowercase contains (%...% in sql)

8.2.2.2 Structure

Line items are expected to have the following fields.

8.2.3 Customers

ResourceType: customer

8.2.3.1 Resource lookups

The following are the ways you can lookup a customer

8.2.3.1.1 Customer Code

The customer is matched with customer code.

Format: code::<code> Params:

• code: The customer's code. Should be an exact match

8.2.3.1.2 Customer Type

The customer is matched with customer code.

Format: type::<type> Params:

• type: The customer's Type Code. Should be an exact match.

8.2.3.1.3 Customer Identifier Type and Number

The customer is matched with customer identifier type and number.

Format: id::<id_type>|<id_number> Params:

• id_type: The customer's identifier type. Should be an exact match
• id_number: The customer's identifier number. Should be an exact match

8.2.3.1.4 Participation Group

The customer is matched with participation group. If the customer is in the group, it should be matched.

Format: group::<group_code>|<participation_value> Params:

• group_code: The group to be matched. Should be an exact match
• participation_value: The participation value that should be matched. Could have the special value * that matches all participation values.

8.2.3.1.5 Present

Evaluates that the customer is present. Basically matches any customer. This is most commonly used when checking for other parameters when selecting customers.

Format: present Params: NA

8.2.3.2 Structure

Customers are expected to have the following fields.

8.2.4 Tenders

ResourceType: tender

8.2.4.1 Resource lookups

The following are the supported ways to lookup this resource.

8.2.4.1.1 Tender Number

The tender is matched with tender number

Format: number::<number> Params:

• number: The tender number. Should be an exact match

8.2.4.1.2 Tender Code

The tender is matched with tender postback code

Format: code::<code> Params:

• code: The tender code. Should be an exact match

8.2.4.1.3 Tender Group Code

The tender is matched with tender group code

Format: group::<group_code> Params:

• group_code: The tender's group code. Should be an exact match

8.2.4.2 Structure

Tenders are expected to have the following fields.

9. Validation Rules

9.1 Create time validation

The following validations MUST be performed when a promotion is created or updated.

9.1.1 Root Structure Validation

• code must be unique across all promotions
• validFrom must be before validTo
• priority must be non-negative
• If images is not set to null, then one child field of the object must be not null

9.1.2 Rules Structure Validation

• All node type values must be from the supported list
• Logic nodes must have at least 1 child
• Property nodes must be a descendant of Resource Nodes
• Comparison nodes must have exactly 2 or 3 children (depending on operator)
• Resource nodes cannot be nested
• Function nodes must have correct parameter count for their function type
• Maximum nesting depth cannot exceed limits defined in 2.5 Collection Constraints

9.1.3 Transformation Validation

• All transformation names must be from the supported list in 5.7.2 Supported Transformations
• Parameter count must match transformation requirements
• valueFrom references must point to a valid code value that comes previously in the list or __input__
• Local variable references (lvar::) cannot reference variable not yet saved
• default must be provided when using returnDefault or forwardDefault
• Cannot create circular dependencies in valueFrom references

9.1.4 Data Array Validation

• All ref:: references in rules and effects must have corresponding fields in every data array object
• Data array cannot exceed 10,000 items
• Each data array object must have consistent field names

9.1.5 Resource Validation

• Resource identifiers must follow format specified in 8.1 Resource Parameter
• Escape sequences must be properly formed
• Referenced properties must exist for the resource type

9.1.6 Effect Free Item Node Validation

Free Item Structure:

• article must use only code_uom:: or ean:: lookup formats (not brand:: or mc::)
• If scalesWithRequirements is true:
  • sourceQuantitySelector is required and must be a non-empty array
  • sourceQuantitySelector array must contain at least 1 selector node
  • sourceQuantitySelector array cannot exceed 50 selector nodes
  • triggerQuantity is required
  • triggerQuantity must be a positive number greater than 0
• If scalesWithRequirements is false:
  • sourceQuantitySelector must not be present
  • triggerQuantity must not be present

Source Selector Node Validation:

• All selector node type values must be from supported list: header, lineItem, customer, tender
• property field must reference a numeric or decimal property from the corresponding resource type
• lookup field must follow resource lookup format specified in Section 8 for that resource type
  • Special case: lookup: "all" is valid for lineItem, customer, and tender types
• For selector nodes with filter:
  • Filter must be a valid Logic Selector Node or Comparison Selector Node
  • Filter children can only be other Selector Nodes (not Rule Nodes)
  • Property Selector Nodes in filters must reference properties from the parent selector's resource type
• Logic Selector Nodes must have at least 1 child
• Comparison Selector Nodes must have exactly 2 or 3 children (depending on comparison operator)
• Function Selector Nodes must have correct parameter count for their function type
• Transformation Selector Nodes follow same validation rules as Rule Transformation Nodes (Section 9.1.3)
• Maximum nesting depth for selectors with filters cannot exceed 10 levels

9.2 Runtime Validation

The following conditions are checked during promotion execution:

9.2.1 Type Conversion Failures

• String to number conversions may fail
  • For transformations they are handled by onError
  • For others they fail the unique execution
• Date parsing may fail
  • For transformations they are handled by onError
  • For others they fail the unique execution
• Boolean parsing may fail
  • For transformations they are handled by onError
  • For others they fail the unique execution

9.2.2 Transformation runtime errors

• Regex patterns might be invalid (handled by onError)
• Array index out of bounds in substring/split operations (handled by onError)
• Null or empty input values (handled by onError)
• Division by zero in modulo operations (handled by onError)

9.2.3 Resource Resolution Failures

• Resource lookups may return no matches (promotion skipped for this context)
• Property extraction may return null values
  • If this is handled (eg: transformation is_null) then it continues
  • Otherwise the current context fails
• ref:: references may not resolve from data array (promotion execution stops with error)
  • This is fatal to the context

9.2.4Effect Discount Node Validation

• applicationType must match one of these formats:
  • "single"
  • "stacking:<count>" where <count> is a positive integer greater than 0
• The stacking keyword without <count> (e.g., just "stacking") is invalid
• <count> must be between 1 and 100 (inclusive)
• If subType is lineItem:
  • applyMechanism is required
  • If applyMechanism is triggerOnly, rules must contain at least one resource node with subType: "article"
  • If applyMechanism is allMatching, the resource field must be provided in the effect

10. Error handling

This has been mentioned within the spec multiple times, this section just brings everything together in a single location for convenience.

10.1 During rules validation

When rules are loaded and the document is validated for evaluation, if an error occurs:

• The entire promotion is considered invalid
• No effects are applied
• Other promotions continue to be accepted

10.2 During rules evaluation

After validation, when its evaluated during a transaction:

• The current unique execution is failed
• No effects applied even if the non-failed part matches correctly
• Other contexts continue to be evaluated

10.3 When reading data from Data array

When reading from the data array, if there is an error due to any reason (data conversion, not found, etc):

• The current unique execution is failed
• No effects applied even if the non-failed part matches correctly
• Other contexts continue to be evaluated

10.4 During Effects application

If during the effects application an error occurs:

• Notify the person using the system
  • Customer case may require system specific conditions
• This unique execution fails
• Other contexts continue to be evaluated

10.5 During Transformation Node

Follow the guidelines provided by the transformation node on the error behaviours.

Appendix

Appendix contains examples for simple and complex promotions for reference.

Appendix 1

Scenario: We want to provide a 10% discount to all items branded with the company "CocaCola".

Specification:

{
	"code": "cocacola10dis2025",
	"name": "CocaCola 10% Discount",
	"description": "For every CocaCola braded item get 10% off",
	"customerDescription": "For every CocaCola braded item get 10% off",
	"images": null,
	"isEnabled": true,
	"validFrom": "2025-12-01T00:00:00.000Z",
	"validTo": "2025-12-31T23:59:59.999Z",
	"lastUpdated": "2025-11-14T17:53:12.129Z",
	"priority": 250,
	"rules": {
		"type": "resource",
		"subType": "lineItem",
		"resource": "brand::cocacola",
		"groupChildren": false,
		"child": {
			"type": "literal",
			"subType": "bool",
			"value": "true"
		}
	},
	"effects": {
		"type": "discount",
		"subType": "lineItem",
		"conditionCode": "DISC",
		"value": 10.0,
		"isPercentage": true,
		"applyMechanism": "triggerOnly",
		"applicationType": "single"
	}
}

How it works:

The rules matches all line items which has the brand cocacola case-insensitive, the child literal gives a true value basically matching all. This is required since the resource node by itself just passes what ever its child gives.

The effect side applies a discount of 10% discount to all matching items.

Appendix 2

Scenario: We want to provide a free apple ean: 11223344 when buying 2 apple juice packets code_uom: 121212, EA, auto scaling based on the amount of soap

Assumptions:

• Apple juice is batch managed and as such can have multiple lines per transaction

Specification:

{
	"code": "bAPPLEPACgAPPLE21",
	"name": "Buy 2 apple juice packets and get 1 fresh apple free",
	"description": "Buy 2 apple juice packets and get 1 fresh apple free",
	"customerDescription": "Buy 2 apple juice packets and get 1 fresh apple free",
	"images": null,
	"isEnabled": true,
	"validFrom": "2025-12-01T00:00:00.000Z",
	"validTo": "2025-12-31T23:59:59.999Z",
	"lastUpdated": "2025-11-14T17:53:12.129Z",
	"priority": 260,
	"rules": {
		"type": "resource",
		"subType": "lineItem",
		"resource": "code_uom::121212|EA",
		"groupChildren": true,
		"child": {
			"type": "comparison",
			"subType": "gte",
			"children": [
				{
					"type": "property",
					"propertyName": "quantity"
				},
				{
					"type": "literal",
					"subType": "decimal",
					"value": "2.0"
				}
			]
		}
	},
	"effects": {
		"type": "freeItem",
		"article": "ean::11223344",
		"conditionCode": "FREE",
		"quantity": 1.0,
		"scalesWithRequirements": true,
		"sourceQuantitySelector": [
			{
				"type": "lineItem",
				"property": "quantity",
				"lookup": "code_uom::121212|EA"
			}
		],
		"triggerQuantity": 2.0
	}
}

How it works

The rules section checks for all line items which match the code and unit of measure provided. This could be multiple in case of multiple batches. Since the resource node is set to groupChildren, it would group all the lines together into one execution context. The lines are then further refined by comparing the quantity of the lines with the literal value 2.0.

On the effect side a free item with barcode 11223344 is provided. The settings work as follows.

• sourceQuantitySelector matches all items with given code and unit of measure as rule side summing up all the quantity.
• Since it is set to scaleWithRequirements, it will give 1 free item (set in quantity) for every 2 from the sourceQuantitySelector
  • 2 gives 1 free
  • 3 still gives 1 free
  • 4 gives 2 free

{
	"type": "comparison",
	"subType": "gte",
	"children": [
		{
			"type": "resource",
			"subType": "lineItem",
			"resource": "code_uom::121212|EA",
			"groupChildren": true,
			"child": {
				"type": "property",
				"propertyName": "quantity"
			}
		},
		{
			"type": "literal",
			"subType": "decimal",
			"value": "2.0"
		}
	]
}

Appendix 3

Scenario: We want to provide the same ruleset (buy x get y) with same validity and name to a bunch of articles.

Specification:

{
	"code": "FRUITFESTIVAL2025",
	"name": "Fruit festival 2025",
	"description": "For each purchase of a 2 fruit juice packets, get a fresh fruit free",
	"customerDescription": "For each purchase of a 2 fruit juice packets, get a fresh fruit free",
	"images": null,
	"isEnabled": true,
	"validFrom": "2025-12-01T00:00:00.000Z",
	"validTo": "2025-12-31T23:59:59.999Z",
	"lastUpdated": "2025-11-14T17:53:12.129Z",
	"priority": 270,
	"rules": {
		"type": "resource",
		"subType": "lineItem",
		"resource": "ref::source",
		"groupChildren": true,
		"child": {
			"type": "comparison",
			"subType": "gte",
			"children": [
				{
					"type": "property",
					"propertyName": "quantity"
				},
				{
					"type": "literal",
					"subType": "decimal",
					"value": "2.0"
				}
			]
		}
	},
	"effects": {
		"type": "freeItem",
		"article": "ref::free",
		"conditionCode": "FREE",
		"quantity": 1.0,
		"scalesWithRequirements": true,
		"sourceQuantitySelector": [
			{
				"type": "lineItem",
				"property": "quantity",
				"lookup": "ref::source"
			}
		],
		"triggerQuantity": 2.0
	},
	"data": [
		{
			"source": "code_uom::112233|EA",
			"free": "ean::112211756"
		},
		{
			"source": "code_uom::112234|EA",
			"free": "ean::112211759"
		},
		{
			"source": "ean::112211721",
			"free": "code_uom::112235|EA"
		},
		{
			"source": "code_uom::112237|EA",
			"free": "ean::112211251"
		}
	]
}

How it works

On the rule side, for every data set (in this case 4) the ruleset is evaluated once.

On each evaluation, all line items which match the lookup value provided in source. This could be multiple in case of multiple batches. Since the resource node is set to groupChildren, it would group all the lines together into one execution context. The lines are then further refined by comparing the quantity of the lines with the literal value 2.0.

On the effect side a free item with given free lookup value is provided. The settings work as follows.

• sourceQuantitySelector matches all items with given code and unit of measure as rule side summing up all the quantity.
• Since it is set to scaleWithRequirements, it will give 1 free item (set in quantity) for every 2 from the sourceQuantitySelector
  • 2 gives 1 free
  • 3 still gives 1 free
  • 4 gives 2 free

As you can see on the data, not all data objects need to have the same selector type. Since they are treated as individual instances, they are not at all linked in anything other than the ruleset and effect definitions.

Appendix 4

Scenario: Progressive discounts on beverages based on spending:

• Spend 500-999.999 MVR → 10% off beverages
• Spend 1000-1999.999 MVR → 15% off beverages
• Spend 2000+ MVR → 20% off beverages

{
	"code": "TIEREDSPEND2025",
	"name": "Tiered spending discount on beverages",
	"description": "Progressive discounts on beverages: 500+ get 10%, 1000+ get 15%, 2000+ get 20%",
	"customerDescription": "Spend more, save more on beverages! Up to 20% off",
	"images": null,
	"isEnabled": true,
	"validFrom": "2025-12-01T00:00:00.000Z",
	"validTo": "2025-12-31T23:59:59.999Z",
	"lastUpdated": "2025-11-14T17:53:12.129Z",
	"priority": 100,
	"rules": {
		"type": "resource",
		"subType": "header",
		"resource": "present",
		"groupChildren": true,
		"child": {
			"type": "logic",
			"subType": "and",
			"children": [
				{
					"type": "comparison",
					"subType": "gte",
					"children": [
						{
							"type": "property",
							"propertyName": "netTotal"
						},
						{
							"type": "literal",
							"subType": "decimal",
							"value": "ref::startAmount"
						}
					]
				},
				{
					"type": "logic",
					"subType": "or",
					"children": [
						{
							"type": "comparison",
							"subType": "eq",
							"children": [
								{
									"type": "transform",
									"transformations": [
										{
											"transformation": "is_null",
											"params": [],
											"onError": "returnInput"
										}
									],
									"child": {
										"type": "literal",
										"subType": "string",
										"value": "ref::endAmount"
									}
								},
								{
									"type": "literal",
									"subType": "bool",
									"value": "true"
								}
							]
						},
						{
							"type": "comparison",
							"subType": "lt",
							"children": [
								{
									"type": "property",
									"propertyName": "netTotal"
								},
								{
									"type": "literal",
									"subType": "decimal",
									"value": "ref::endAmount"
								}
							]
						}
					]
				}
			]
		}
	},
	"effects": {
		"type": "discount",
		"subType": "lineItem",
		"resource": "mc::beverages",
		"conditionCode": "ref::code",
		"value": "ref::discount",
		"isPercentage": true,
		"applyMechanism": "allMatching",
		"applicationType": "single"
	},
	"data": [
		{
			"startAmount": "2000.0",
			"endAmount": null,
			"discount": "20.0",
			"code": "BEV20"
		},
		{
			"startAmount": "1000.0",
			"endAmount": "2000.0",
			"discount": "15.0",
			"code": "BEV15"
		},
		{
			"startAmount": "500.0",
			"endAmount": "1000.0",
			"discount": "10.0",
			"code": "BEV10"
		}
	]
}

How it works

On the rule side, for every data set (in this case 3) the ruleset is evaluated once.

On each evaluation, the header is matched with the ruleset.

• netTotal is matched to be greater than or equal to the startAmount
• Since its an and the following is only matched if the previous statement succeeds
• Then the second condition is checked as follows:
  • The data item endAmount is transformed via is_null which will produce a value true or false
  • if true (end value is null) then the second condition auto succeeds due to the or logic node
  • if false the netTotal is rematched to netTotal this time checking for less than only

On the effect side a discount of discount percent is given to all items with the merchandising category beverages (matched case-insensitive). Since applyMechanism is all matching, it gives it to all matching lines and each line will only receive it once since the applicationType is single.

Appendix 5

Scenario VIP customers (defined as GOLD) customers get 20% off on electronics

Assumptions

• A customer group with code LOYALTY exists with participation value providing the tier of participation.

{
	"code": "VIP_ELEC_2025",
	"name": "VIP Electronics Priviledge",
	"description": "VIP customers ",
	"customerDescription": "Spend more, save more on beverages! Up to 20% off",
	"images": null,
	"isEnabled": true,
	"validFrom": "2025-12-01T00:00:00.000Z",
	"validTo": "2025-12-31T23:59:59.999Z",
	"lastUpdated": "2025-11-14T17:53:12.129Z",
	"priority": 100,
	"rules": {
		"type": "logic",
		"subType": "and",
		"children": [
			{
				"type": "resource",
				"subType": "customer",
				"resource": "present",
				"groupChildren": true,
				"child": {
					"type": "comparison",
					"subType": "eq",
					"children": [
						{
							"type": "transform",
							"transformations": [
								{
									"transformation": "extract_kv",
									"params": ["::", ",", "LOYALTY"],
									"onError": "returnDefault",
									"default": "NONE"
								}
							],
							"child": {
								"type": "property",
								"propertyName": "customerGroups"
							}
						},
						{
							"type": "literal",
							"subType": "string",
							"value": "GOLD"
						}
					]
				}
			},
			{
				"type": "resource",
				"subType": "lineItem",
				"resource": "mc::electronics",
				"groupChildren": false,
				"child": {
					"type": "literal",
					"subType": "bool",
					"value": "true"
				}
			}
		]
	},
	"effects": {
		"type": "discount",
		"subType": "lineItem",
		"resource": "mc::electronics",
		"conditionCode": "VIPELEC",
		"value": 20.0,
		"isPercentage": true,
		"applyMechanism": "allMatching",
		"applicationType": "single"
	}
}

How it works

On the rule side the root is an and which checks the following:

• There is a customer present and they have the group LOYALTY
  • If the group is found, the participation value is returned
  • If not found then NONE is returned
  • This value is then compared with GOLD
• An item with merchandising category electronics exists

On the effect side it applies a discount of 20% to all the items with merchandising category electronics, once per item.