Liquid upgrade

We are upgrading how we render liquid in your messages to better support you. The version we use to render your liquid depends on when you created your account with us.

 What liquid version are you on?

If your Customer.io account was created on or after Nov 28, 2023, you are using the latest liquid version for all messages. If your Customer.io account was created before Nov 28, 2023, see Changing your liquid version for more info.

See below for the differences between the two versions.

How to check your liquid version

Within any message editor, hover over the last saved date at the top to see the liquid version you’re using.

The cursor hovers over the last saved date at the top right of a message composer. At the bottom of the tooltip is Liquid Version: Legacy.
The cursor hovers over the last saved date at the top right of a message composer. At the bottom of the tooltip is Liquid Version: Legacy.

If you’re using the legacy liquid version, you may be able to upgrade to the latest version. If you upgraded a message to the latest liquid but want to return it to legacy due to syntax issues, you can also downgrade.

Changing your liquid version

We are in the process of upgrading all accounts to the latest liquid version. We are gradually rolling it out, which means some customers will have the latest liquid before others.

The latest liquid version offers improved filters (e.g. default filter), faster rendering, and better tools for troubleshooting liquid syntax. See the differences between our legacy and latest liquid versions below.

For accounts created on or after Nov 28, 2023, you’re already using the latest liquid version for all messages.

For accounts created before Nov 28, 2023, see Upgrade your liquid version for more information:

  • you can upgrade your liquid version on a template-by-template basis. That is, if you upgrade an email then copy it, the copy will use the latest liquid, too. Soon, all new messages will use the latest liquid by default.
  • you can also downgrade the liquid version if necessary.

Upgrade your liquid version

For accounts created before Nov 28, 2023, you can upgrade to the latest liquid version on a template-by-template basis. That is, if you upgrade an email then copy it, the copy will use the latest liquid, too. Go to a message with legacy liquid, click Actions or three horizontal dots in the top right, and see “Upgrade Liquid version…” in the dropdown.

In the top right of an email, the Actions dropdown is open. The bottom option to upgrade liquid versions is highlighted.
In the top right of an email, the Actions dropdown is open. The bottom option to upgrade liquid versions is highlighted.

 Check out the differences between our two versions of liquid to make sure you’re ready to upgrade.

To upgrade, click “Upgrade Liquid version…” then confirm your action. This will only upgrade the liquid version for the message you are on. You must go into each message to upgrade the version.

You cannot upgrade snippets and layouts directly; these will render based on the liquid version of the message they are used in.

Downgrade your liquid version

For accounts created before Nov 28, 2023, you can also downgrade a message to the legacy liquid version if you manually upgraded previously; you cannot downgrade messages that were created with the latest liquid version.

To downgrade, go to a message with the latest liquid, click Actions or three horizontal dots in the top right, and click “Switch Liquid version…” in the dropdown.

In the top right of an email, the Actions dropdown is open. The option to switch liquid versions is highlighted.
In the top right of an email, the Actions dropdown is open. The option to switch liquid versions is highlighted.

 We recommend you don’t downgrade unless you need to quickly resolve syntax issues caused by the upgrade.

Click “Switch Liquid version…” then confirm your action. This will only downgrade the liquid version for the message you are on. You must go into each message to downgrade the version.

Fallback for both latest and legacy liquid versions

This section is useful if you want to reference liquid across messages and not worry about which liquid version you’re on. You’ll assign a variable to establish the liquid verison of the message and reference the variable to display the correct output.

 You must assign the variable and reference it in the template itself or in a snippet. You cannot assign a variable in a snippet, then reference it in a template and vice versa.

  1. Assign the variable in the template or snippet followed by this conditional:

    {% assign liquid_version = nil | default: "latest" %}{% unless liquid_version == "latest" %}{% assign liquid_version = "legacy" %}{% endunless %}
    
  2. Then you can reference the variable in a conditional to display the proper content:

    {% if liquid_version == "latest" %}liquid that renders for latest liquid version{% else %}liquid that renders for legacy liquid version{% endif %}
    

Below is a breakdown of what is deprecated and new across liquid versions. A fallback like the one above can help you make sure, for instance, that operators supported by the legacy liquid version render when possible while a replacement for these operators renders with the latest version:

{% assign liquid_version = nil | default: "latest" %}{% unless liquid_version == "latest" %}{% assign liquid_version = "legacy" %}{% endunless %}

{% if liquid_version == "latest" %}{{ product_color | default: "red" }}{% else %}{% if product_color != blank %}{{ product_color }}{% else %}red{% endif %}{% endif %}

Differences in liquid versions

Deprecated with the latest liquid version:

  • timezone - We deprecated the timezone tag in the latest liquid version. Moving forward, use timezone as an argument with the date filter instead.
    • Legacy: {{ created_at | timezone: 'America/New_York' }}
    • Latest: {{ created_at | date: '%Y-%m-%d %H:%M:%S', timezone: 'America/New_York' }}
    • Note: We support the Asia/Riyadh timezone in the latest version of liquid. We no longer support:
      • Asia/Riyadh87
      • Asia/Riyadh88
      • Asia/Riyadh89
      • Mideast/Riyadh87
      • Mideast/Riyadh88
      • Mideast/Riyadh89
  • htmlencode - Use escape to escape a string moving forward.
    • Legacy: {{ "win+help@customer.io" | htmlencode }} or {{ "win+help@customer.io" | escape }}
    • Latest: only {{ "win+help@customer.io" | escape }}

New to the latest liquid version:

  • default - It’s finally here! Now you can set a default value when one does not exist. You must use default rather than checking for empty strings using == blank or != blank.
  • json_array_uniq - Now you can evaluate an array of JSON objects to output an array containing all the unique objects based only on the value of the passed-in key name. Use the filter to_json if you need to output string values.
  • break - You can use a break tag to exit a loop.

Differences between tags supported in both versions

These tags exist across both versions, but behave differently in the latest liquid:

  • timezone - You can offset the timezone in minutes, not hours. For instance, 360 would offset the timezone by -6:00 hours.
  • currencyand rounded_currency - These filters accept both a locale and currency code. The legacy version only accepted a locale. These locales are only supported in the latest version: gsw-CH, ja-JP, kk, mg, sv-FI, sv-SE, uk, zh-Hant-MO, zh-MO. The locale zh-YUE is only supported in the legacy version.
  • escape - Use url_encode to encode URLs instead.
  • sort - This no longer throws an error, preventing messages from sending, when a list/array contains null values. However, when an array contains null values, it won’t reorder the array.
  • concat - Now this accepts an object or an array.
  • sha256 - This converts a string to the same output as hmac_sha256.
  • times - Compare examples from the tag list to see when outputs contain decimals or not. In the latest version, if the output is a whole number, it will never contain a decimal.
  • divided by - Compare examples from the tag list to see when outputs contain decimals or not. In the latest version, if the output is a whole number, it will never contain a decimal.
  • modulo - The output will always be a positive number, even when there’s a negative number as input.
Copied to clipboard!
  Contents
Is this page helpful?