Aggregations

How to aggregate a condition's matches

The matches of a condition's main matcher can be aggregated based on another field's values. Those values are aggregated using a specified operator and the results of the aggregation is compared against a provided value using the aggregation's matcher to add additional restrictions and define the overall aggregated condition's matches.

Key	Type	Required	Description	Example
field	String		The resource's field on which to perform the aggregation (expressed in dot notation). Must be an attribute within the related condition's scope, cannot be a resource.	"order.line_items.quantity"
operator	String		The operator to be used on the field value to aggregate the results (check the list of available operators).	"sum"
matcher	String		The matcher to be used against the operator result and the provided value (check the list of available matchers).	"gteq"
value	Integer		The value to be compared against the operator result on the field value using the matcher.	2

Multiple aggregations (on the same or different fields) are computed according to an AND logic.

The allowed aggregations field values are limited by the related condition's field value, meaning that the former must be within the scope defined by the latter (i.e. an attribute of one of the entities specified in the condition's field). For example, if the condition's field is order.line_items.sku.code you can aggregate over order.line_items.quantity but not over order.customer.total_orders_count because the customer entity is not within the scope set by the condition.

Example

The following condition uses a couple of aggregations to check if an order contains at least three units in total of products tagged with any of a given set of tags and the cheapest one costs no less than a specific value

• The main matcher checks which line items of the order are associated with an SKU tagged with one of the two desired tags.

• The first aggregation's operator adds those line items' quantities and the related aggregation's matcher checks if the resulting sum is greater than or equal to 3.

• The second aggregation's operator identifies the cheapest of those line items' unit amount cents and the related aggregation's matcher checks if that cost exceeds the desired value.

"conditions": [
  {
    "field": "order.line_items.sku.tags.name",
    "matcher": "is_in",
    "value": [ "summer2022", "vipsale" ],
    "aggregations": [
      {
        "field": "order.line_items.quantity",
        "operator": "sum",
        "matcher": "gteq",
        "value": 3
      },
      {
        "field": "order.line_items.unit_amount_cents",
        "operator": "min",
        "matcher": "gt",
        "value": 5000
      }
    ]
  }
]