Market variables in templates

Variables

There are four variables for Market:

• products — function selects products

{products("<filter>" 10 "manufacturer_name" "desc")}

• sku — function selects SKUs

{sku("<filter>" 10 "manufacturer_name" "desc")}

• orders — the function selects orders from the list of profile orders

{orders("<filter>" 10 "status" "asc")}

• order — the function selects one order from the list of profile orders

{order("<filter>")}

Function arguments

("<filter>" 10 "manufacturer_name" "desc")

Argument	Required	Description
"<filter>"	Yes	The filter is a string of conditions. Allows you to select products, SKUs, orders, or order lines that meet specified conditions. For example, you can select products from the same manufacturer or orders that exceed a specific cost. See below for details.
10	Yes	Limit. How many array elements to iterate over. The maximum value is 30. For example, if you specify 10, then the filter will select the first ten elements from the array.
"manufacturer_name"	No	Sort objects by the specified field. By default — no sort.
"desc"	No	Sort direction. asc — ascending (by default) desc — descending

Filter

The filter consists of fields and operators. Each object in the market has fields. For example, products and SKUs have a name field (product name). Orders have a total_price field (total cost of the order). In a filter, you specify a field and a value that it should match. If the field of the object matches the value, this object will be selected and its data can be substituted into the template.

Filter example

Let's add the "Orders" variable to the template:

{orders ("order.total_price == '200 USD' && (order.custom_fields.field == 'lead._region')" 10 "id" "desc")}

The bold part of the variable is the filter. Let's consider it in parts:

• order.total_price == '200 USD': the condition will select all orders with a cost equal to $200.

• order.custom_fields.field == 'lead._region' - the condition will select orders with the additional 'field'. You can specify any additional (custom) field instead of "field". The specified equality means that the value of the "field" must match the value of the region in the customer's profile ("lead._region").

• && is an operator. It indicates that both conditions must be met.

• The number 10 indicates the number of output objects, "id" indicates the filter field, and "desc" indicates the descending sort.

Below are the fields and operators available in the filter.

Operators and functions in a filter

Operator	Description	Example	What will be selected
>	greater	order.delivery_cost > '10 USD'	Orders with shipping costs over $10
>=	greater or equal	order.delivery_cost >= '10 USD'	Orders with a shipping cost of $10 or more
<	less	sku.count < '10'	The number of SKUs for sale is less than 10
<=	less or equal	sku.count <= '10'	The number of SKUs for sale is 10 or more
==	equals	order.status == '1' order.custom_fields('date') == '2024-12-25'	Orders with "new" status Orders with date December 25, 2024
!=	not equal	product.manufacturer_name != 'Apple'	Products not manufactured by Apple
&&	AND (both conditions match)	product.manufacturer_name == 'Apple' && product.price < '200 USD'	Apple products cost more than $200
||	OR (one of the conditions matches)	sku.manufacturer_name == 'MSI' || sku.manufacturer_name == 'Acer'	SKU with manufacturer MSI or Acer
in('<field_name>', 'value1', 'value2'...'valueN')	The field value (<field_name>) matches one of the specified values ('value1', 'value2')	in(product.external_id,'1','2','3')	Products with ID equal to 1, 2 or 3
contains('<field_name>', 'value1', 'value2'...'valueN')	One of the array elements matches one of the specified values. <field_name> — array 'value1', 'value2' — values to match. Used if the field is an array, i.e. contains several elements (for example: categories, images, additional fields).	contains(product.categories,'smartphone')	Products included in the category "smartphone"
len('<field_name>', <operator>, <number> )	Checks the length of an array. Compares the number of elements in the array with the specified number. <field_name> — array field (e.g., product.pictures) <operator> — comparison operator (>, >=, <, <=, ==, !=) <number> — integer for comparison.	len(product.pictures, !=, 0)	Products that have a number of pictures not equal to zero (i.e., have at least one picture)

Working with custom fields

Two syntaxes are available for filtering by custom fields:

Universal syntax (recommended)

(product.custom_fields('external_id'))

info

We recommend using the universal syntax product.custom_fields('external_id') because it supports all types of identifiers — both numeric and string, including special characters. This option guarantees correct filtering regardless of your custom field's external_id format.

Examples:

{for $product in products("product.custom_fields('123') == 'red'")}
{for $product in products("in(product.custom_fields('color'), 'red', 'blue')")}
{for $product in products("sku.custom_fields('45') > '100'")}

String syntax (limited)

(product.custom_fields.field_name)

info

The old syntax product.custom_fields.field_name can only be used if the field's external_id consists exclusively of alphabetic characters and does not contain numbers, hyphens, or other special characters.

Example:

{for $product in products("product.custom_fields.brand == 'Apple'")}

List of available fields in filters

Products

Prefix — product.

Field	Description
product.external_id	Product ID
product.name	Product name
product.manufacturer_name	Manufacturer's name
product.url	URL of the product page on the store website
product.pictures	Product Image URL
product.count	Number of products available for sale
product.is_available	Is the product in stock at the store?
product.delivery	Possibility of delivery (for all regions to which the store delivers)
product.barcode	List of product barcodes from the manufacturer
product.categories	Product category ID
product.custom_fields.<field_external_id>	Custom product field ID. For numeric IDs use custom_fields('123')

SKU

Prefix — sku.

Field	Description
sku.external_id	SKU ID
sku.name	SKU name
sku.manufacturer_name	Manufacturer's name
sku.url	URL of the SKU page on the store website
sku.pictures	SKU image URL
sku.count	Number of SKUs available for sale
sku.is_available	Is the SKU in stock at the store?
sku.delivery	Possibility of delivery (for all regions to which the store delivers)
sku.barcode	List of SKU barcodes from the manufacturer
sku.categories	SKU category ID
sku.custom_fields.<field_external_id>	Custom sku field ID. For numeric IDs use custom_fields('123')

Orders

Prefix — order.

Field	Description
order.external_id	Order ID
order.status	Order status ID 1 - new 2 - delivered 3 - paid 4 - cancelled 5 - partial refund
order.delivery_cost	Shipping cost
order.total_price	Total cost of the order. It consists of the number of each item in the order and the cost of delivery.
order.custom_fields.<external_id поля>	Custom order field ID
order.real_create_time	Order creation time
order.real_update_time	Order update time
order.region_external_id	Region ID

Sorting by Custom Fields

Sometimes you need to sort objects by their custom field values (the custom_fields object).
Custom fields are stored in the database as a JSON string. Therefore, to access a field inside the JSON for sorting, you can use the -> operator.

Example of accessing a key:

custom_fields -> 'priority'

Usage in a sort parameter function (using products as an example):

{for $index $el = products("contains(product.categories,'smartphone')" 3 "custom_fields -> 'priority'" "desc")}
{$el.name} — {$el.price}
{else}
if empty array
{end}

In this example, the product list is first filtered by the smartphone category, then sorted by the value of the priority key inside custom_fields in descending order, and the first 3 results are displayed.

info

Important

• The -> operator is used only in the sort parameter to access a JSON key.
• For filtering by custom fields, use the dot notation from the "Filter" section, for example: order.custom_fields.field == 'value'.
• The -> operator is not a market operator — it is a database operator (PostgreSQL) used for the query, so this sorting method should be considered a workaround.

Use cases

Any variable in the market is an array. For example, products contains an array of all products uploaded to the platform, and orders contains an array of orders for one profile. To iterate over an array, use loops.

Searching the array of products (products)

Outputs 5 Apple products in an email:

You might be interested in these products:
{for $index $el = products("product.manufacturer_name == 'Apple'" 5 "external_id" "desc")}
{$el.name} - {$el.price}
{else}
if empty array
{end}

7 cheapest smartphones:

The best smartphone prices for you and your loved ones:
{for $index $el = products("product.categories == 'smartphone'" 7 "price" "asc")}
{$el.name} - {$el.price}
{else}
if empty array
{end}

Goods with delivery:

Delivered to your door:
{for $index $el = products("product.delivery == true" 10 "name" "desc")}
{$el.name} - {$el.price}
{else}
if empty array
{end}

Search SKU (sku) array

Smartphones under 20000:

Smartphones you will like:
{for $index $el = sku("contains(sku.categories,'smartphone') && sku.price < '20000 RUB'" 3 "price" "asc")}
{$el.name} - {$el.price}
{else}
if empty array
{end}

IPhone with more than 128GB of storage:

Enough memory for everything:
{for $index $el = sku("contains(sku.name,'IPhone') && sku.custom_fields.memory >= '128'" 10 "name" "desc")}
{$el.name} - {$el.price}
{else}
if empty array
{end}

Searching the array of all orders (orders)

Orders at pickup points:

Orders are waiting for you at the pickup point:
{for $index $el = orders("order.status == '2'" 10 "external_id" "desc")}
Order # {$el.external_id}
Due: {$el.total_price}
{else}
if empty array
{end}

List of new orders:

New orders in the last week:
{for $index $el = orders("order.status == '1'" 20 "external_id" "desc")}
Order # {$el.external_id}
Due: {$el.total_price}
{else}
if empty array
{end}

Search for items in order with id = '0001' (order + lines)

{for $index $el = order("order.external_id == '0001'")}
 {if $index equal "lines"}
  {for $i $line = $el}
    {$line.name} position name: {$line.name}
    {$line.price} Item price: {$line.final_price_of_line}
  {end}
 {end}

 {if $index equal "delivery_cost"}
   {$el} {$delivery_cost} {$el}
 {end}
 {if $index equal "total_price"}
   To pay: {$el}
 {end}

{else}
if empty array
{end}

List of available fields for substitution in the template

products/sku

Substitution field	Description
external_id	Product/SKU ID
name	Product/SKU name
manufacturer_name	Manufacturer's name
url	URL of the product page on the store website
pictures	List of URL links to product images (array)
count	Quantity of products/SKU available for sale
available	Is the product/sku in stock at the store?
delivery	Possibility of delivery (for all regions to which the store delivers)
barcode	List of product barcodes from the manufacturer (array)
categories	List of product/SKU category IDs (array)
custom_fields.<external_id поля>	Custom field ID. For numeric IDs and special characters use custom_fields('external_id') syntax.
price	Current product price
old_price	Previous product price
regional_data.<region_external_id>.count	Quantity of products/SKU available for sale in the specified region. regional_data is product/sku data that varies by region. <region_external_id> is region ID.
regional_data.<region_external_id>.delivery	Possibility of delivery to the specified region
regional_data.<region_external_id>.available	Is the product/SKU in stock in the specified region?
regional_data.<region_external_id>.price	Product/SKU price in the specified region

orders / order

Substitution field	Description
external_id	Order ID
status	Order status ID
delivery_cost	Shipping cost
total_price	Total cost of the order. It consists of the cost of each item in the order and the cost of delivery.
custom_fields.<external_id поля>	Custom field ID. For numeric IDs and special characters use custom_fields('external_id') syntax.
create_time	Order creation time
update_time	Order update time
region.external_id	Region ID
lines	Order line. Only for the order function.

lines

Substitution field	Description
id	Line ID
external_id	Order line additional ID
custom_status_external_id	Order line status ID
base_price_per_item	Base price
final_price_of_line	Final price
count	Quantity of products or skus in the line
custom_fields.<field_external_id>	ID for the custom field of the order line. For numeric IDs and special characters use custom_fields('external_id') syntax.
product_external_id	Line product ID
name	Line name
manufacturer_name	Manufacturer's name of the line product
url	URL of the page of the line product
pictures	List of URL links to images of the line product
balance	Stock quantity
available	Is the line product in stock at the store
delivery	Possibility of delivery of the line product (array)
barcodes	List of barcodes of the line product (array)
categories	List of category IDs of the line product

info

Custom field override priority:
(defines which field values are applied first)

SKU > Product > Order-item