Filter rules

This article explains what filtr rules are and how to set them in Ingrid Merchant Platform

    What are filter rules?

    Filter rules in Ingrid are used to define the behavior of the delivery options that Ingrid Delivery Checkout should produce for each checkout session.

    Filter rules decide if Carrier Product or Delivery Category should be valid for showing delivery options. All rules validate the given statement and return a boolean response(True/False) for each rule. Based on if the full rule execution is True or False, the Category(or Carrier Method) is Shown(True) or "Not Shown"(False). 

    Setup guidance

    TIP: filter rules are the key to control the cases when you want to show/remove a delivery option in the Checkout. Consider all the various conditions when you want to remove a delivery offering from a Delivery Checkout widget. Be it a particular weight limitation, or a specific country zone or the size of the package (for example for the lockers products).

    How to add a filter rule in Ingrid Merchant Platform?

    There are numerous functions in Ingrid available for you to adjust carrier product or delivery product and make a service available/unavailable for an end customer. Depending on the setup, please consider which of the above would benefit you. A carrier product could have two delivery types linked and the filter could affect both. A delivery category can be linked to a single or more carrier products, which gives us another option of control.

    You might have a contract in place which requires from you to ship a product under 7kg. Let us have a look on how a solution for such scenario can be implemented.


    Steps:

    1. From your Ingrid Merchant admin go to Delivery Checkout > Regions > Specific region

    2. Select a specific Delivery Category or Carrier Product.

    Note: Filter rule could be set on a delivery category or on a carrier product.

    3. Set a filter rule in the "Filter rules section".

    TIP: Mind the values of the dimensions and parameters you set the filter rules with. In Ingrid, we work with: grams, millimeters, and cents. It means:

    Weight
    - should be defined in grams
    Dimensions (Length, Width, Height) - in millimeters
    Price / Values - Cent based (10.50 € = 1050)

    Available functions

     

    Value, weight & quantity

    Description

    total_value >= 22500

    The total value of the cart is displayed in cents (‘2000’ is ‘20.00’)

    total_weight <= 7000

    Summarises the total weight (in grams) of all the cart items

    all_cartitems_below_weight(15000)

    Checks if the weight of every item is below indicated weight (in grams)

    Total_quantity > 3

    Checks if the quantity of cart items is above the indicated value

    Dimensions

    Description

    every_item_fits_size(600, 600, 500)

    Check for every item that all dimensions are equal to or within the provided size. No specific order like Height, Width, Length is applied.

    all_cartitems_dims_fits_size(400,200,300)

    Checks that all cart items fit separately in a specific dimension.

    1. No specific order required for product or box dimensions
    2. No item number restriction
    3. Two highest dimensions have their maximum values compared, while a sum of the 3rd one must be below or equal to a maximum. 

    all_cartitems_sum_of_two_largest_dims_below(800)

    Sum of the two largest dimensions should not exceed given value (mm).

    total_volume < 4500

    Sum on each item volume (mm^3)

    all_cartitems_below_dims(1500, 1500, 1500)

    Each cart item has dimensions below indicated values (height, length, width / mm)

    all_cartitems_dims_sum_below(3000)

    Sum of dimensions of each cart item is lower than indicated value (mm)

    all_cartitems_has_dims()

    Checks if all cart items has dimensions present

    total_items_height > 4000

    Summarises all cart items’ heights. Takes the quantity into consideration. 

    all_cartitems_shortest_dim_sum_below(1890)

    Finds the shortest dimension of cart items and sums these up and secures that the sum is lower than the given value (mm). 

    max_item_length < 1000

    Finds and operates on the longest length for any cart item regardless of the quantity. 

    max_item_long_edge < 1200

    Finds and operates on the longest side of the cart items in the cart. Used when master data for dimensions are unclear. 

    all_cartitems_above_dims (100, 200, 300)

    Each cart item has dimensions above indicated values (height, length, width / mm)

    all_cartitems_largest_surface_area_below (1200000)

    The carrier option will appear if the largest surface of the cart item is smaller than 1200000 mm2

    max_item_circumference <= 3000

    The maximum circumference of the item is 3000 mm, where circumference = length + (2*(width + height))

    Attributes

    Description

    all_cartitems_have_attr('sendasletter')

    Checks and verifies if all cart items have the set attribute. The set attributes could be multiple. 

    contains(cart_items_attributes(), 'Example')

    Checks and verifies if at least one item in the cart has the attribute.

    contains(cart_attributes(), 'Chairs')

    Checks if the attributes are set for the cart.
    This also includes cart group in the delivery checkout request to Ingrid API.

    not(contains_any(cart_items_attributes(),('example1', 'example2')))

    Checks the lack of attributes presence

    cart_and_cart_items_attributes()

    Return attributes of both cart and items in the cart.

    any_cart_item_has_substr_in_name(“examp”)

    Checks if cart item has particular substring

    any_cart_item_has_sku(“1234567”)

    Check cart items’ SKU.

    at_least_n_cartitems_have_attr(1,'bulky')

    Checks if the desired number of items has a particular attribute. If we use, for example, number “2”, then at least two items in the cart need to have the attribute “bulky”. 

    Date & Time

    Description

    is_one_of_weekdays(now_time(), 'Europe/Stockholm', 'wed')

    Checks if provided time is within the specified weekday

    between_hours('17:00', '20:00', 'Europe/Stockholm', 'wed', 'fri')

    Checks if provided time is within the specified hours and weekdays.

    time_now_shipping_date_time_start_diff_in_days <=4

    Checks if the cart has a shipping date.

    Shipping_date_end_start_diff_in_days < 2

    Subtracts start date from end date in the shipping date sent for the session and calculates this difference. 

    Postal Codes

    Description

    in_range(postal_code(), 00000,21110) || in_range(postal_code(), 23844,59999)

    Checks if the address is located within a covered range. There may be many post code ranges present in such rule (“||” stands for OR).

    not(in_range(postal_code(),11120,11124) && not(in_range(postal_code(),11127,11127))

    Checks if the postcode is not present within indicated postal code range (“&& stands for AND).

    matches_any_pattern(postal_code(), '1[0,1]*', '1[2-5]*', '1[6-9]*')

    Postal code matches any pattern containing indicated values. 

    matches_any_pattern(postal_code(), '1234*', 'PH123*', '123[1-6]*', '1[2,3][1-6]*')

    Postal code matches any pattern containing indicated values. 

    not(matches_any_pattern(postal_code(), '350[0,1,7,8]*', '352[0-9]*')

    Postal code doesn’t match to indicated pattern.

    contains(array('11121', '35004', '35008'), postal_code())

    Postal code matches to the indicated numbers. Can be used for random postcodes without following a particular pattern. 

    not(contains(array('11121', '35004', '35008'), postal_code()))

    Postal code doesn’t match any of the indicated numbers. Can be used for random postcodes without following a particular pattern.

    Other Filters

    Description

    contains(cart_vouchers, 'HEAVY')

    Confirms all vouchers with the value ‘HEAVY’ present on the cart

    total_discount >= 2000

    Total value of discounts in cents (‘2000’ is ‘20.00’

    out_of_stock == false

    Flag indicating if the item is currently out of stock

    pre_order == true

    Sets if this is a preorder or not.

    Caution

     

    Since the filter rules syntax is sensitive to potential typos and errors, it is highly recommended to first apply them on stage environment. Before publishing filter rule updates on prod, it’s best to check the Ingrid Checkout Widget test module within the Ingrid Merchant Platform first. If the session will return an error, it means that the filter rule most likely has a flaw. If you can’t find the root cause, feel free to consult our support team (support@ingrid.com).

    Filter rules present nearly unlimited possibilities of affecting the Ingrid session. Feel free to experiment on stage to find the most fitting scenarios. It’s also worth considering to use A/B Testing to find the most profitable conditions on prod. 

    Modalities

     

    Every filter rule is built with syntax. It can be a simple statement, limited only to one rule or an advanced, multi-level structure. The rules can work separately from each other, or be linked with operators. This can lead to filtering in and out certain services in a very elaborate context that suits your exact needs.

    Operators

    The filter rules can be linked with the following characters:

    && - AND statement 

    It creates a dependency under which every filter rule condition has to be met. 

    Examples:

    • total_weight <=30000 && all_cartitems_dims_sum_below(2500) && max_item_length < 1500
      Total weight of the article must be lower than 30000 grams AND all their dimension sums has to be below 2500 milimeters AND no item can be longer than 1500 milimeters. 
    • not(contains(cart_items_attributes(), 'bulky')) && contains(cart_items_attributes(), 'light')
      The cart item can’t contain an attribute ‘bulky’ AND must contain an attribute ‘light’. 

    I| - OR statement 

    It creates a dependency under which at least one fulter rule condition has to be met. 

    Example:

    • in_range(postal_code(), 55302, 56636) || in_range(postal_code(), 58128, 59077)
      The postal code has to be either in range between 55302-56636 OR in range between 58128-59077.

    Both of these operators can be mixed within one sentence:

    not(contains(cart_items_attributes(), 'Example')) && in_range(postal_code(),13025,13025) || in_range(postal_code(),13033,13034) || in_range(postal_code(),13036,13036)

    The item in the cart cannot have an attribute “not-in-stock”, as well as the user can’t be located within the different postal code ranges.

    Negation

    There are two ways to alter the stated conditions within the syntax:

    1. By adding “not” in front of the condition, you can create a negative statement. For example, instead of creating a list of “positive” zip code ranges, you can pick this specific one that won’t be available for the service:
      not(in_range(postal_code(), 11120, 12010))
      It’s also useful with any different filter rule, counting the attribute-based ones:
      not(contains_any(cart_items_attributes(), ('not-in-stock’')))
    2. By adding an exclamation mark “!” in front of the condition, you can overturn the conditions to work in an opposite way. It’s best to describe it on example:
      !all_cartitems_below_weight(68000)
      If all the cart items are above 68000 grams, the carrier option will be shown. 

    This overturn can be used within the sentence:
    all_cartitems_below_weight(68000) && !all_cartitems_below_weight(18000)

    If all the cart items will be below 68000 grams and above 18000 grams, the service will be shown. 

     

    Pattern rules

    matches_any_pattern(base, pattern 1, ... , patterN)

    // Reports whether at least one pattern matches the base argument.

    // For pattern should be used Glob syntax (more info about Glob syntax)

     

    Pattern syntax:

    '*' - matches any sequence of characters.

    '?' - matches any single character

    '[123aB]' - matches one character given in the bracket

    '[0-6]' - matches one character from the range given in the bracket

    All rules validate the given statement and return a boolean response(True/False) for each rule. Based on if the full rule execution is True or False, the Category(or Carrier Method) is Shown(True) or "Not Shown"(False).