Expressions
Overview
Expressions present a powerful tool to derive values from product data. It is useful to create SEO optimized titles and descriptions, as well as derive arbitrary attributes like tax-included prices, tax, shipping, etc.
Expressions compose of tokens (variables that represents context data that is being pulled into the feed like variant price, options, etc), constants (texts, numbers), operators (math operators, string concatenation), function (text case manipulation, date calculation, etc.) and self expressive keywords like "if", "then", "else".
Some examples where expressions can be used:
- A custom field representing tax that equal to 21% of product price.
- A "Shipping and included" price that equal product price added with a shipping fee for a marketplace that take only shipping and tax included prices.
- A condition to include or exclude variant from feed based on its metafield and/or other data
Following screenshot is showing a condition that match when one of following conditions are met
- quantity > 10
- price between 10 and 20
- has a product metafield with namespace "my_fields" and key "always_include" which has value "yes"
Editing expression
Editing expression is made easier with some help of the expression editor
To hide complexity, an expression can be in read-only mode, showing a general description of the expression underneath. Click on 'Edit' button to reveal the expression and edit it.
A token can be added by typing the single quote ('), supported tokens will be listed in a dropdown and one needs to be selected from the list to be added into the expression box. Added tokens have a greyed background and can be changed by clicking on it.
Depending on context, typing the double quote (") may display a list of applicable constants in a dropdown. Added constants will have a greyed background, but with a green color instead of orange like the tokens.
A good example is editing the Google product category. The list includes thousands of categories, so the dropdown is helpful to select the right category.
Examples
String concatenation
Regular expression match
Regular expression is really powerful (and complicated) way to check for patterns in string values. Examples include:
- If Product description include one of the following words: "shirt", "jean", "child" or "women":
- 'Product description' ~= "(shirt|jean|child|women)"
- If Product tile starts with "Men" or "Boy". This does not include titles that have the word men somewhere else in the sentence
- 'Product title' ~= "(^men|^boy)" will match "Men's wear" and "Boy's jeans" but not "T-shirt for men"
"Looking-up" expression
Following screenshot is showing an expression derive a tax-included price value from the value of product type.
- If the product is clothing then the price should include a 10% rise for tax
- if it's is kitchen ware or household then the tax included is 20%
- otherwise the price stay the same
"Price range" expression
"Price range" expressionSometime you may need to specify shipping cost for product according to its price and/or weight
Following is an expression for
- If price > 100 shipping is free
- if 50 < price < 100 shipping is 10% of price
- if price < 50 then shipping is 5
"List returning" expression 
Some attributes expect a list of values will have this icon next to their names, , including the product details, product highlights, additional images and promotion ID. Expressions for these attributes should return one of the following forms:
1/ An array in the form of ("value1","value2","value3")
2/ A metafield that contains a list of values. For example additional images could be provided by a metafield that returns a list of files.
3/ (deprecated) A string, which then be processed as below:
- for product details and product highlights, the string will be split into lines and the list of lines will then be used as the list of values. If the content (highlights, details) needs to be in multi-line, use an array as option 1 above.
- for additional images and promotion ID, the string will be split by commas (,)
Option 3 also includes support of text metafields (single line and multi line), whose values will be processed accordingly.
"Money returning" expression
Some attributes expect money amount with currency. For example cost of good sold. The expression should return BOTH the amount and the currency, e.g "12USD" or "3 GBP".
"Measurement returning" expression
These attributes expect a value and a unit. For example unit pricing measure and unit pricing base measure. The expression should return BOTH the value and the unit, e.g. "1.3kg" or "12 floz".
"Boolean" expression
These attributes accept yes/no values. The expression should be either a logic expression, or an expression that return "yes" or "no".
Example of a logic expression
Price > 10 or Quantity < 3
The same logic expression re-written to return "yes"/"no"
if Price > 0 or Quantity < 3 then "yes" else "no"
Reference
There are 2 basic types of consts: numbers and strings. Numbers may be floating point or integers. Strings should always be double-quoted. Types get automatically converted when possible, for example:
"1" + 2 == "12"
"12" - 1 == 11
"12" * 1 == 12
| Values | Description |
|---|---|
| 43, -1.234 | Numbers |
| "hello" | String |
| " \" \\ " | Escaping of double-quotes and blackslash in string |
BEWARE!
Strings must be double-quoted! Single quotes are for tokens.
| Numeric arithmetic | Description |
|---|---|
| x + y | Add |
| x - y | Subtract |
| x * y | Multiply |
| x / y | Divide |
| x ^ y | Power |
| x mod y | Modulo |
-1 mod 3 == 2.
| Comparisons | Description |
|---|---|
| x == y | Equals |
| x != y | Does not equal |
| x < y | Less than |
| x <= y | Less than or equal to |
| x > y | Greater than |
| x >= y | Greater than or equal to |
| x == y <= z | Chained relation, equivalent to (x == y and y <= z) |
| x ~= y | Regular expression match |
| x in (a, b, c) | Equivalent to (x == a or x == b or x == c) |
| x not in (a, b, c) | Equivalent to (x != a and x != b and x != c) |
| Boolean logic | Description |
|---|---|
| x or y | Boolean or |
| x and y | Boolean and |
| not x | Boolean not |
| if x then y else z | If boolean x is true, return value y, else return z |
| ( x ) | Explicit operator precedence |
| Objects and arrays | Description |
|---|---|
| (a, b, c) | Array |
| a in b | Array a is a subset of array b |
| x of y | Property x of object y |
| Functions | Description |
|---|---|
| abs(x) | Absolute value |
| ceil(x) | Round floating point up |
| empty(x) | True if x is undefined, null, an empty array or an empty string, or an invalid number (result of division by zero, for example) |
| exists(x) | True unless x is undefined or null |
| floor(x) | Round floating point down |
| log(x) | Natural logarithm |
| log2(x) | Logarithm base two |
| log10(x) | Logarithm base ten |
| max(a, b, c...) | Max value (variable length of args) |
| min(a, b, c...) | Min value (variable length of args) |
| round(x) | Round floating point |
| sqrt(x) | Square root |
| replace(x, searchRegex, replaceWith, fallback) | Look for all regular expression matches by searchRegex in x, and replace with replaceWith. The optional fallback if presented will be returned if no matches is found. |
| default(x, fallback1, fallback2, ..., fallbackN) | Look from left to right and return the first non-empty value found. This function is helpful to cascade fallback values for optional expression (non-existing metafield, etc.). |
| toFixed(x, decimalPlaces) | Converts a number to a string, rounding the number a specified number of decimal. |
| date(dateValue, deviation, deviationType) | Modify input date by deviation amount of time. deviationType could be "second", "minute", "hour", "day", "week", "month", "year".To get a date 3 months from now date('{now}', 3, "month") Same time last week date('{now}', -1, "week") |
| substring(stringValue, start, end?) | Return a sub string of the stringValue which starts at index start and ends up to (but not including) index end. First character is at index 0. |
| case(stringValue, caseType) | Modify the case of stringValue. caseType takes one of the following values- "low": uncapitalize whole text - "up": capitalize whole text - "sentence": uncapitalize whole text and capitalize the first character - "title": uncapitalize whole text and capitalize the first character of each words |
| capture(stringValue, captureRegex, defaultValue) | Capture part of the stringValue using captureRegex. This is useful in cases like:- Extracting colors from product title. The colors are known in advanced (e.g the list of colors is known). Falling back to "white" if no color is found: capture( Product title, "\\b(red|green|blue)\\b","white")- Extracting colors from product title. The color is the last word in product title: capture( Product title, "\\b(\\w+)$")- Extracting the first line from Product HTML description capture( Product description HTML, "(.*?)(<br>|$)") |