📣 Product updates December 2023. Learn more →
Vero logo

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.

      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

        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
        {{ 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.

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

          Boolean operators:

          Input Output
          or
          or
          and
          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: "%e %B %Y" }}
            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

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

            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.

            minus

            Subtracts a number from another number.

            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

              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.

              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:

              Input Output
              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.