---
title: Variables and Liquid in Workflow Transactional Email
description: >-
  Pass Shopify Flow data into email subjects, bodies and HTTP requests with
  Liquid. Full reference for variables, secrets, shop values, loops and
  conditionals.
source_url:
  html: >-
    https://docs.workflow-transactional-email.app/variables-and-liquid
  md: >-
    https://docs.workflow-transactional-email.app/variables-and-liquid.md
---

# Variables and Liquid

Everything dynamic in this app is Liquid - the same templating language Shopify themes use. You write a placeholder, and the app fills it in at send time.

> [!TIP]
> If you are here because a value came out **blank**, go straight to [Passing data from Shopify Flow](https://docs.workflow-transactional-email.app/passing-data-from-shopify-flow.md). That page covers the Variables (JSON) field, the copy-paste helper in the app, and the line-items trap that causes most empty values.

## The namespaces

| Namespace | Where the value comes from | Available in |
| --- | --- | --- |
| `{{ variables.key }}` | The **Variables (JSON)** field on the Shopify Flow action | Email subject and body, HTTP URL, headers and body |
| `{{ secrets.key }}` | The **Secrets** page | Same, plus SMTP username and password |
| `{{ shop.name }}`, `{{ shop.domain }}`, `{{ shop.email }}` | Your store | Email and HTTP actions |
| `{{ language }}` | The **Language** the Flow step sent, else the layout's main language | Email subject, preview text and body - see [Send emails in your customer's language](https://docs.workflow-transactional-email.app/layout-languages.md) |
| `{{ unsubscribe_link }}`, `{{ unsubscribe_url }}` | The recipient's unsubscribe link, in **marketing** layouts only | Email body; empty in transactional layouts - see below |
| `{{ flow.key }}` | The raw Shopify Flow payload | **HTTP requests only** |

The **System Variables** card in the editor lists the shop values with their current contents, and clicking one copies it.

## Passing variables from Shopify Flow

In the Flow action, put a JSON object in the **Variables (JSON)** field:

```
{
  "firstName": "{{ customer.firstName }}",
  "orderNumber": "{{ order.name }}",
  "total": "{{ order.totalPriceSet.shopMoney.amount }}"
}
```

Then reference them anywhere in the layout:

```
Hi {{ variables.firstName }}, your order {{ variables.orderNumber }} is on its way.
```

The keys are yours to choose. Whatever you name on the left is what you use after `variables.`, matching exactly on spelling and capitalisation.

You do not have to write this JSON by hand. Every layout has a **Use in Shopify Flow** card with the correct JSON ready to copy - see [Passing data from Shopify Flow](https://docs.workflow-transactional-email.app/passing-data-from-shopify-flow.md).

## Filters

Standard Liquid filters work. The most useful one is `default`, which protects you from an empty value:

```
Hi {{ variables.firstName | default: "there" }}
```

Others behave as you would expect:

```
{{ variables.productTitle | upcase }}
{{ variables.total | round: 2 }}
{{ variables.note | truncate: 100 }}
```

> [!NOTE]
> Templates are rendered leniently on purpose. An unknown variable renders as an empty string and an unknown filter is ignored, rather than throwing an error and failing the send. That keeps a typo from blocking a customer's email - but it also means a typo shows up as a blank, not an error message. The app watches for this and flags it on the History entry; see below.

## When a variable renders blank

A live send that renders any referenced variable to nothing gets an **Empty variables** badge in **History**. Opening the entry names them and separates two different problems:

- **Sent by Shopify Flow but empty** - the key was in your JSON, but Flow produced no value. Usually a wrong property path, or a field that is genuinely empty for that record (a guest checkout has no customer first name).
- **Not sent by Shopify Flow at all** - the key is missing from your JSON entirely.

Adding a `| default:` fallback marks the blank as intentional, and the app stops warning about it.

## Conditionals and loops

Use the **HTML / Code** block for conditionals:

```
{% if variables.isVip %}
  <p>As a VIP you get free shipping on this order.</p>
{% else %}
  <p>Spend a little more to unlock free shipping.</p>
{% endif %}
```

Use the **Loop** block to repeat over an array, for example order line items:

```
{% for item in variables.items %}
  <tr>
    <td>{{ item.title }}</td>
    <td>{{ item.quantity }}</td>
    <td>{{ item.price }}</td>
  </tr>
{% endfor %}
```

Pass the array from Flow as JSON:

```
{
  "items": [
    { "title": "Classic White T-Shirt", "quantity": 2, "price": "29.00" },
    { "title": "Eco Water Bottle", "quantity": 1, "price": "19.00" }
  ]
}
```

To preview a loop in the builder, enter the same JSON array as the value in the **Test Variables** tab.

> [!WARNING]
> Reading a list directly does not work. `{{ order.lineItems.variant.title }}` returns nothing, because an order has many line items. Loop over them instead. This is the most common cause of an empty variable.

## Objects behave differently in email and HTTP

This is the one sharp edge worth knowing.

- In an **HTTP request**, interpolating an object or array serialises it to JSON automatically. `{{ variables.records }}` becomes a proper JSON array in the request body. A `json` filter is also available if you want to be explicit.
- In an **email**, there is no such conversion. Interpolating a whole object renders the literal text `[object Object]`.

So in emails, always reach into the object rather than printing it:

```
Wrong:  {{ variables.customer }}
Right:  {{ variables.customer.firstName }} {{ variables.customer.lastName }}
```

Or loop over an array instead of printing it whole.

## Secrets in templates

Reference a stored secret the same way:

```
Authorization: Bearer {{ secrets.airtableAccessToken }}
```

Use the exact syntax `{{ secrets.keyName }}`. These do **not** work:

- `{{ secret.keyName }}` - singular
- `{{ secrets['keyName'] }}` - bracket syntax

Key names are case-sensitive. See [Secrets](https://docs.workflow-transactional-email.app/secrets.md).

## Body override for HTTP requests

The HTTP action's variables field has a second mode. Pass a `body` key and it replaces the saved request body entirely:

```
{
  "body": { "anything": "you like", "shaped": ["however"] }
}
```

This is useful when the payload shape is decided by an earlier Flow step. The one exception: if your saved body itself references `{{ variables.body }}`, it is treated as an ordinary variable instead.

## Testing what you wrote

The on-page preview does **not** evaluate Liquid - it shows the tags as written. To see resolved values:

- For emails, use **Send test email** from the layout editor.
- For HTTP requests, use the **Test** button, which shows the **Resolved URL** and **Resolved Body** alongside the response.

> [!WARNING]
> **Test Variables are not live values.** They drive the preview and test sends only. A real Flow run ignores them completely and uses whatever the Flow action sends. A test email that looks perfect proves your design works - it proves nothing about your Flow configuration. Always confirm with a real workflow run and check History afterwards.

## The unsubscribe link in marketing layouts

A layout whose **Email type** is **Marketing** gets two more variables. Each recipient of a marketing email has their own unsubscribe link, and these place it:

- `{{ unsubscribe_link }}` renders a link with the **Unsubscribe link text** from Settings (or the layout's own).
- `{{ unsubscribe_url }}` renders the bare address, for a button or an anchor you style yourself.

```
<p>No longer interested? <a href="{{ unsubscribe_url }}">Unsubscribe here</a>.</p>
```

You do not have to use them: every marketing email gets an unsubscribe footer appended anyway. When the rendered body already contains the link, the footer leaves its unsubscribe sentence out and appends only the company details. In the subject and the preview text both variables render as nothing, and in a **transactional** layout they are always empty. See [Marketing emails and unsubscribes](https://docs.workflow-transactional-email.app/marketing-emails.md).

## Related

- [Passing data from Shopify Flow](https://docs.workflow-transactional-email.app/passing-data-from-shopify-flow.md) - the Variables (JSON) field in depth.
- [Build an email layout](https://docs.workflow-transactional-email.app/build-an-email-layout.md) - where these variables go.
- [Marketing emails and unsubscribes](https://docs.workflow-transactional-email.app/marketing-emails.md) - marketing layouts, the unsubscribe footer and the unsubscribe list.
- [Secrets](https://docs.workflow-transactional-email.app/secrets.md) - storing credentials safely.
- [Make an HTTP request from Shopify Flow](https://docs.workflow-transactional-email.app/make-an-http-request.md) - variables in a real request.
