🎉 We’ve launched a new product, Vero Newsletters. Read more about this release and our vision here ↗

Personalizing emails and push notifications using Liquid

What is Liquid?

Liquid is an open-source language, created by Shopify, that enables dynamic content to be displayed on websites, emails and mobile push notifications (where the service provider supports Liquid). It offers a huge amount of flexibility to customize your messages, and it can often save you from syncing additional data to your email platform – allowing you to create more engaging and relevant content, faster.

This guide explains how Liquid works and provides a summary of the most commonly used Liquid tags and filters for email and push notifications, with examples of how to use them. You can also find a list of Vero-specific Liquid shortcodes that make personalizing email and push notifications that bit easier.

How does it work?

The static elements of an email are written in HTML (for push messages it’s written in JSON), and the dynamic elements are written in Liquid. The Liquid elements act as placeholders: just before the message is sent to the recipient, the Liquid is replaced and interpreted using the data tracked in your email platform, such as Vero.

When using Liquid, you should always review the output using the preview and test features in your email platform before activating your campaign.

Objects

Objects tell Liquid the location of the data that you want to load in the content of your email or push message.

For example, the two main objects in Vero are:

  • user. – indicates the data stored in the customer profile.
  • event. – indicates the data is stored against an event the user has triggered.

Objects are followed by the variable name, and are denoted by double curly braces: {{ object.variable }}. For example:

Input Output
{{ user.first_name }} Jack
{{ event.purchased_item }} trainers
{{ event.subscription_plan }} annual

With Vero, you can also create custom objects that pull data from your internal or third-party APIs.

Tags

Tags create the logic and conditions for the content you want to load in your email. They are denoted by curly braces and percent signs: {% and %} . Tags and the markup inside them are not visible to the email recipient.

Below are a few of the most commonly used tags in email templates.

if

Translates the Liquid code and displays in the email if a certain condition is true.

Input Output
{{user.account_status}} customer
{% if user.account_status == 'customer' %}
Log in to your account
{{% endif %}}
Log in to your account
Input Output
{{ user.account_status }} trial
{% if user.account_status == 'trial' %}
Watch the video
{% endif %}
Watch the video

unless

Translates the Liquid code and displays in the email if a certain condition is not true (the opposite of ‘if’).

Input Output
{{ user.first_name }}
{{ user.account_status }}
James
customer
Hi {{ user.first_name }},
{% unless user.account_status == 'cancelled' %}
Log into your account
{% endunless %}
Hi James,
Log into your account
Input Output
{{ user.first_name }}
{{ user.account_status }}
Zach
cancelled
Hi {{ user.first_name }},
{% unless user.account_status == 'cancelled' %}
Log into your account
{% endunless %}
Hi Zach,

elsif/else

Allows inclusion of multiple conditions within an if or unless statement.

Input Output
{{event.discount_amount}} 20.00
{% if event.discount_amount == "15.00" %}
Get $15 off your next order!
{% elsif event.discount_amount == "20.00" %}
Get $20 off your next order!
{% else %}
Recommend a friend and get $10 off your next order.
{% endif %}
Get $20 off your next order!

Operators

Comparison operators can be used with if,elsif, else and unless tags; they don’t work anywhere else in Liquid.

== equals
!= does not equal
> greater than
< less than
>= greater than or equal to
<= less than or equal to

Boolean operators:

or
and

Filters

Filters can be used to change the output value or format of a Liquid object. Below are some of the Liquid filters that are most commonly used in email templates.

append

Joins two strings together and returns the value. For example:

Input Output
{{ 15 | append: '%' }} 15%
{{ event.discount_amount | append: '%' }} 15%

date

Converts a unix timestamp into another date format. The format for this syntax is the same as strftime.

Input Output
{{ event.collection_date }} 1544268600
{{ event.collection_date | date: "%e %B %Y" }} 12 August 2018
{{ event.collection_date | date: "%A %e %B" }} Sunday 12 August
{{ event.collection_date | date: "%D" }} 12/08/2018
{{ event.collection_date | date: "%v" }} 12-Aug-2018

Note: Unix time is UTC, see sections current date/ time and timezones to learn how to display the date and time for a different timezone.

divided_by

Divides a number by the number you specify. The value returned is rounded down to the nearest integer, if the divisor is an integer.

Input Output
{{ 15 | divided_by: 3 }} 5

downcase

Reformats the string as all lowercase letters.

Input Output
{{ event.viewed_product }} Dusky Pink Trainers
{{ event.viewed_product | downcase }} dusky pink trainers

first

Displays the first character or item in a string.

Input Output
{{ user.full_name }} Sarah Jones
{{ user.full_name | first }} S

You can also include a split filter to display part of the string.

Input Output
{{ "Alice, Sarah, Zach" | split: ", " | first }} Alice

minus

Subtracts a number from another number.

Input Output
{{ 10 | minus: 2 }} 8
{{ 180.333 | minus: 8 }} 172.333

You can also include the round filter to round the output to the nearest integer, or specifiy the number of decimal places you want to round to.

Input Output
{{ 180.333 | minus: 8 | round: 2 }} 172.33
{{ 180 | minus: 5.50 | round: 2 }} 174.5

N.B. Trailing zeros are not displayed when using these standard Liquid maths filters. With Vero, you can use the custom Liquid filter, precision to display trailing zeros – for when you want to calculate and display prices/ currency formats in your emails.

modulo

Returns the remainder value after the division of one number by another.

Input Output
{{ 5 | modulo: 2 }} 1
{{ 180.57 | modulo: 4 }} 0.57

plus

Adds a number to another number.

Input Output
{{ 4 | plus: 6 }} 10
{{ 163.539 | plus: 8 }} 171.539

prepend

Attaches a specified string to the beginning of a string.

Input Output
{{ event.product_price }} 42.95
{{ event.product_price | prepend: "$" }} $42.95
{{ event.product_price | prepend: "£" }} £42.95

replace

Replaces every occurrence of a specified substring with another, within a string.

Input Output
{{ user.subscription_plan }} Gold subscription
{{ user.subscription_plan | replace: "subscription", "plan" }} Gold plan

remove

Removes every occurrence of a specified substring within a string.

Input Output
{{ event.order_number }} 00012336
{{ event.order_number | remove: "000" }} 12336

times

Multiplies one number with another number and returns the value.

Input Output
{{ 5.95 | times: 2 }} 11.9
{{ 5.95 | times: 3 }} 17.85

upcase

Changes the string to all uppercase letters

Input Output
{{ user.subscription_plan }} Gold subscription
{{ user.subscription_plan | split: " " | first | upcase }} GOLD

Vero-specific Liquid code

We’ve extended the standard Liquid functionality with a series of custom functions that make it even quicker and easier to personalize your emails. The following custom Liquid objects and filters can be used in Vero:

fallback

Allows you to add a default value, should a value not exist. The default value will be displayed where the value on the left is empty.

Input Output
{{ user.firstname }}
Hi {{ user.firstname | fallback: "there" }}, Hi there,

precision

Rounds the output to a specified number of decimal places, observing trailing zeros. This is helpful when using Liquid maths filters in your email, for example where you want to display a price/ currency format.

Input Output
{{ event.item_price }} 72.50
Total: ${{ event.item_price | minus: 8 }} Total: $64.5
Total: ${{ event.item_price | minus: 8 | precision: 2 }} Total: $64.50

Current date/time

extra.time.now returns the current datetime as a Unix time.

The Unix epoch (or Unix time or POSIX time or Unix timestamp) is the number of seconds that have elapsed since January 1, 1970.

You can transform this value into a readable date using the standard Liquid date filter. The datetime is calculated at the point in time at which the email sent.

Input Output
{{ extra.time.now }} 1564489806
{{ extra.time.now | date: "%A %e %B" }} Tuesday 30 July
{{ extra.time.now | date: "%v" }} 30-Jul-2019

There is only one Unix time and it is created by using the UTC/GMT time zone.

If you want to display the exact date and time for a different timezone, you can use plus or minus to offset in seconds UTC time. You can find a list of timezones and the seconds to which you need to offset, here.

For example, if you wanted the email to display the current date and time in Sydney (AEST) you would add 36000 seconds, which is UTC +10:00.

Input Output
{{ extra.time.now | date: "%A %e %B, %R" }} Wednesday 1 August, 23:30
{{ extra.time.now | plus: 36000 | date: "%A %e %B, %R" }} Thursday 2 August, 09:30

Remember, extra.time.now is calculated as the point in time the email is sent.

future date

You can also use extra.time.now to display a future date, based on the time the recipient is sent a behavioural email. You can add time to the current date by using epoch time, which converts as follows:

Time period seconds
1 hour 3600
1 day 86400
1 week 604800
1 month (30.44 days) 2629743
1 year (365.24 days) 31556926

For example, if the email was sent on Tuesday 30 July and you wanted your offer to expire in 7 days:

Input Output
20% off until {{ extra.time.now | plus: 604800 | date: "%A %e %B" }} 20% off until Tuesday 6 August

timezones

If you track a property following the ISO 8601 format, you can use time_zone to convert UTC/GMT to your specified time zone.

Input Output
{{ event.purchase_date }} 2017-10-08T04:46:10Z
{{ event.purchase_date | date: "%A %e %b, %R" }} Sunday 8 Oct, 04:46
{{ event.purchase_date | time_zone: 'Sydney'; | date: "%A %e %b, %R" }} Sunday 8 Oct, 15:46
{{ event.purchase_date | time_zone: 5 | date: "%A %e %b, %R" }} Sunday 8 Oct, 09:46
{{ event.purchase_date | time_zone: -7 | date: "%A %e %b, %R" }} Saturday 7 Oct, 21:46

Important: Before launching your email campaign, always double check your Liquid code using Vero’s preview and test features.