Liquid Template Engine
Liquid is a templating language developed by Shopify. It's designed to work with objects and substitution arrays using loops, conditionals, and filters. This makes it easy to create flexible email templates that are automatically populated with dynamic data passed in the payload of the email/send and template/set methods. Using advanced substitution logic also helps reduce template size, speeds up request processing, and allows for more adaptable email campaigns with minimal effort.
Substitution variables can be used in the following parameters of the email/send and template/set methods:
- body.html
- body.plaintext
- body.amp
- subject
- headers
- from_name
- options.unsubscribe_url
Liquid Use Cases
1. Accessing Nested Objects
You can reference nested variables inside substitution objects. This is especially useful for structured data like user info, order details, addresses, etc.
Below is an example of a request using the global_substitutions parameter for email/send and template/set, or substitutions for email/send):
|
{ "substitutions": { "person": { "name": "John", "secondName": "Doe", "age": "26" } } } |
Example usage in an email (applies to parameters like body.html, body.plaintext, body.amp, subject, headers, options.unsubscribe_url, from_name in both email/send and template/set):
| "html": "<p>Hello, {{ person.name }} {{ person.secondName }}!</p>" |
2. Loops: Rendering Arrays
Loops allow you to dynamically output lists – e. g., items in an order, recommendations, event attendees, survey answers, etc.
Request data containing an array:
|
"substitutions": { "products": [ { "title": "Samsung Galaxy A53", "price": "320$" }, { "title": "Xiaomi Redmi Note 12", "price": "270$" }, { "title": "Motorola G82", "price": "250$" } ] } |
Template:
|
<ul> {% for product in products %} <li> {{ forloop.index }}. {{ product.title }} – {{ product.price }} </li> {% endfor %} </ul> |
3. Generating Link Lists
Use Liquid to add dynamic links based on user data, product names, IDs, and more – ideal for buttons, catalogs, and listings.
Request:
|
"substitutions": { "products": [ { "title": "Samsung Galaxy A53", "url": "https://shop.example.com/samsung-galaxy-a53" }, { "title": "Xiaomi Redmi Note 12", "url": "https://shop.example.com/redmi-note-12" }, { "title": "Motorola G82", "url": "https://shop.example.com/motorola-g82" } ] } |
Template:
|
<ul> {% for product in products %} <li> <a href="{{ product.url }}"> {{ product.title }} </a> </li> {% endfor %} </ul> |
4. Conditional Statements
Conditionals let you render different blocks of content depending on variable values. For example, you can show a custom greeting to new users or offer discounts to returning customers.
Request:
|
{ "substitutions": { "user": { "is_new": true } } } |
Template:
|
{% if user.is_new %} Welcome! {% else %} Glad to have you back! {% endif %} |
5. Filters
Filters let you format data right within the template – change text case, add prefixes, replacing strings, or format numbers and dates.
|
Filter |
JSON Data |
Template Code |
Rendered Output |
|
capitalize (converts first letter to uppercase) |
{ "name": "ann" } |
Hello, {{ Trigger.name | capitalize }}! |
Hello, Ann! |
|
upcase (converts the string to uppercase) |
{ "promo": "JULY2025" } |
Promo code: {{ Trigger.promo | upcase }} |
Promo code: JULY2025 |
|
downcase (converts the string to lowercase) |
{ "promo": "JULY2025" } |
Promo code: {{ Trigger.promo | downcase }} |
Promo code: july2025 |
|
replace (replaces a substring with new value) |
{ "phone": "(555) 012-34-56" } |
Phone: {{ Trigger.phone | replace: "(555)", "+1 (555)" }} |
Phone: +1 (555) 012-34-56 |
|
default (sets the default value) |
{ "name": "" } |
Hi, {{ Trigger.name | default: "customer" }}! |
Hi, customer! |
|
date (formats date) |
{ "delivery_date": "2025-05-01" } |
Delivery date: {{ Trigger.delivery_date | date: "%d.%m.%Y" }} |
Delivery date: 01.05.2025 |
Full Example: email/send Request Using a Liquid Template
Below is a complete working example of a request:
|
{ "api_key": "KEY", "message": { "template_engine": "liquid", "body": { "html": "<h1>Hello, {{ user.name }}!</h1><p>Your selected {{ lookingfor.deviceType }}: {{ lookingfor.screenResolution }}, {{ lookingfor.ram }} RAM.</p>{% for product in products %}<div><a href='{{ product.url }}'>{{ product.title }}</a> — {{ product.price }}</div>{% endfor %}" }, "subject": "Your Recommendations", "from_email": "[email protected]", "from_name": "SENDER_EMAIL", "recipients": [ { "email": "[email protected]", "substitutions": { "user": { "name": "John" }, "lookingfor": { "deviceType": "tablet", "screenResolution": "1920x1080", "ram": "4GB" }, "products": [ { "title": "Amazon Tablet", "price": "$50", "url": "https://..." } ] } } ] } } |
For more details on Liquid, check out Shopify’s official Liquid documentation.
Other template engines UniOne supports:
