Expressions

Expressions allow defining predicates. These can be used to match certain line items or customers for example.

Format

The model is a tree based structure. The root always has a type of Group and must have at least one clause.

The types of nodes are:

• Group
• Property
• Expression
• PropertyComparison

Group

The Group type has a conjunction property that defines how the clauses are evaluated (supported values are And and Or). If there is only one clause the conjunction isn't used.

Below is an example of the JSON:

{
  "type": "Group",
  "conjunction": "And",
  "clauses": []
}

Property

The Property type allows writing a predicate for comparing a property value (passed into the /evaluate endpoint) with a pre-defined value. E.g. an expression such as "Customer has a segment of VIP" could be defined as below.

{
  "type": "Property",
  "property": "Customer.Segments",
  "operator": "contains",
  "value": "VIP"
}

Expression

The Expression type allows referencing other expressions. See Global Expressions section below. An example clause is:

{
  "type": "Expression",
  "expressionId": "902f6ee4-6cfc-460f-89a9-739eb7659fb0",
  "value": true
}

The value property determines if the referenced expression should evaluate to true or false for this clause to be considered true. Generally it is better to use true and update the referenced expression as needed to avoid any confusing double negative logic.

PropertyComparison

The PropertyComparison type allows comparing two property values. E.g. "Line Item List Price is equal to Line Item Discounted Price".

{
  "type": "PropertyComparison",
  "leftProperty": "LineItem.DiscountedPrice",
  "rightProperty": "LineItem.ListPrice",
  "operator": "equals"
}

Note. the data type of the two properties being compared needs to match. E.g. you can't compare a Date property to a String property

Example

Below is a complex example of an entire expression.

{
  "conjunction": "And",
  "type": "Group",
  "clauses": [
    {
      "type": "Property",
      "property": "LineItem.Category",
      "operator": "equals",
      "value": "Shorts"
    },
    {
      "conjunction": "Or",
      "type": "Group",
      "clauses": [
        {
          "expressionId": "902f6ee4-6cfc-460f-89a9-739eb7659fb0",
          "value": true,
          "type": "Expression"
        },
        {
          "type": "PropertyComparison",
          "leftProperty": "LineItem.DiscountedPrice",
          "rightProperty": "LineItem.ListPrice",
          "operator": "equals"
        }
      ]
    }
  ]
}

Operators

The list of valid operators can be obtained from the Operators API endpoint in the Builder API.

The available operators are determined by the data type of the property used as well as if the value in the expression or the property value (value provided to the Processor API) are multivalued. The operators endpoint allows passing these options to give you the available operators.

If both are multivalued then you are comparing two lists and the only available operator at present is intersects.

Below are two examples to provide more details.

Example: Expression value is Multivalued, Property value isn't Multivalued

E.g. Shipping Method Name is one of "Standard" or "Express":

Below is the example request to setup a Shipping method name property (POST to /properties):

The context property has an ID of 51b7f1d9-db71-4e86-9398-0eee9ebe22a2 in this example.

{
  "name": "ShippingMethodName",
  "displayName": "Shipping Method Name",
  "parentId": "51b7f1d9-db71-4e86-9398-0eee9ebe22a2",
  "dataType": "String",
  "multivalued": false
}

Below is an example expression using this property (ShippingMethodName property has been setup on a called Context):

{
  "conjunction": "And",
  "type": "Group",
  "clauses": [
    {
      "type": "Property",
      "property": "Context.ShippingMethodName",
      "operator": "inlist",
      "value": ["Standard", "Express"]
    }
  ]
}

Below is an example of the JSON passed to the /evaluate endpoint:

{
  "basket": {
    "items": [
      {
        "quantity": 2,
        "price": 58.99
      }
    ]
  },
  "context": {
    "currencyCode": "GBP",
    "shippingMethodName": "Standard"
  },
  "settings": {
    "dataInstance": "Live"
  }
}

Example: Expression value is not Multivalued, Property value is Multivalued

E.g. one of the Customer Segments is "VIP":

Below is the example request to setup a Segments property (POST to /properties):

The customer property has an ID of a1f8bf6f-63e0-4085-be19-78f92d874dad2 in this example.

{
  "name": "Segments",
  "displayName": "Segments",
  "parentId": "a1f8bf6f-63e0-4085-be19-78f92d874dad",
  "dataType": "String",
  "multivalued": true
}

Note multivalued is true because the value passed to the /evaluate endpoint is an array.

Below is an example expression using this property:

{
  "conjunction": "And",
  "type": "Group",
  "clauses": [
    {
      "type": "Property",
      "property": "Customer.Segments",
      "operator": "contains",
      "value": "VIP"
    }
  ]
}

Below is an example of the JSON passed to the /evaluate endpoint:

{
  "basket": {
    "items": [
      {
        "quantity": 2,
        "price": 58.99
      }
    ]
  },
  "context": {
    "currencyCode": "GBP"
  },
  "customer": {
    "segments": ["VIP"]
  },
  "settings": {
    "dataInstance": "Live"
  }
}

Global Expressions

Global expressions provide the ability to save and re-use expressions in discounts and other global expressions. For example, you may setup a global expression that matches if the user is in a segment of VIP. This expression can then be referenced by discounts without having to specify the exact VIP logic again.

These are managed using the expressions endpoints in the Builder API (see Expressions API Definitions).

There are two types of global expressions:

• Line Item
• Eligibility

Line item expressions can only use line item properties. During evaluation individual line items are evaluated against the expression.

Eligibility expressions are the opposite, they can only use non line item properties. They do not have access to line item properties during evaluation.