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:

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

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

{{ user.first_name }}

{{ event.purchased_item }}

{{ event.subscription_plan }}

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.

{{ user.account_status }}

{% if user.account_status == 'customer' %}
  Log in to your account
{% endif %} }}

unless

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

{{ user.first_name }}
{{ user.account_status }}

Hi {{ user.first_name }},
{% unless user.account_status == 'cancelled' %}
  Log into your account
{% endunless %}

{{ user.first_name }}
{{ user.account_status }}

Hi {{ user.first_name }},
{% unless user.account_status == 'cancelled' %}
  Log into your account
{% endunless %}

elsif/else

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

{{ event.discount_amount }}

{% 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 %}

Operators

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

==

!=

>

<

>=

<=

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:

{{ 15 | append: '%' }}

{{ event.discount_amount | append: '%' }}

date

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

{{ event.collection_date }}

{{ event.collection_date | date: "%e %B %Y" }}

{{ event.collection_date | date: "%e %B %Y" }}

{{ event.collection_date | date: "%D" }}

{{ event.collection_date | date: "%v" }}

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.

{{ 15 | divided_by: 3 }}

downcase

Reformats the string as all lowercase letters.

{{ event.viewed_product }}

{{ event.viewed_product | downcase }}

first

Displays the first character or item in a string.

{{ user.full_name }}

{{ user.full_name | first }}

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

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

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

minus

Subtracts a number from another number.

{{ 10 | minus: 2 }}

{{ 180.333 | minus: 8 }}

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.

minus

Subtracts a number from another number.

{{ 180.333 | minus: 8 | round: 2 }}

{{ 180 | minus: 5.50 | round: 2 }}

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.

{{ 5 | modulo: 2 }}

{{ 180.57 | modulo: 4 }}

plus

Adds a number to another number.

{{ 4 | plus: 6 }}

{{ 163.539 | plus: 8 }}

prepend

Attaches a specified string to the beginning of a string.

{{ event.product_price }}

{{ event.product_price  prepend: "$" }}

{{ event.product_price  prepend: "$" }}

replace

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

{{ user.subscription_plan }}

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

remove

Removes every occurrence of a specified substring within a string.

{{ event.order_number }}

{{ event.order_number | remove: "000" }}

times

Multiplies one number with another number and returns the value.

{{ 5.95 | times: 2 }}

{{ 5.95 | times: 3 }}

upcase

Changes the string to all uppercase letters

{{ user.subscription_plan }}

{{ user.subscription_plan | split: " " | first | upcase }}

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.

{{ user.firstname }}

Hi {{ user.firstname | fallback: "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.

{{ event.item_price }}

Total: ${{ event.item_price | minus: 8 }}

Total: ${{ event.item_price | minus: 8 | precision: 2 }}

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.

{{ extra.time.now }}

{{ extra.time.now | date: "%A %e %B" }}

{{ extra.time.now | date: "%v" }}

Current date/time

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.

{{ extra.time.now | date: "%A %e %B, %R" }}

{{ extra.time.now | plus: 36000 | date: "%A %e %B, %R" }}

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:

1 hour

1 day

1 week

1 month (30.44 days)

1 year (365.24 days)

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

20% off until {{ extra.time.now | plus: 604800 | date: "%A %e %B" }}

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.

{{ event.purchase_date }}

{{ event.purchase_date | date: "%A %e %b, %R" }}

{{ event.purchase_date | time_zone: 'Sydney'; | date: "%A %e %b, %R" }}

{{ event.purchase_date | time_zone: 5 | date: "%A %e %b, %R" }}

{{ event.purchase_date | time_zone: -7 | date: "%A %e %b, %R" }}

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