Online
Bento
View markdown

Liquid Template Guide

Liquid is a template language you can use inside Bento emails. It lets you insert subscriber data, show or hide content with conditionals, and format values with filters. Use it to greet subscribers by name, show different offers to different people, and build dynamic content like cart reminders and coupon codes. This guide covers the Liquid tags, filters, and helpers available in Bento.

The Basics

These core tags cover the most common needs: links, buttons, images, audio, and name personalization.

Name Personalization

Use these to make your emails feel more human, even when subscriber data is incomplete.

First name or fallback

Simple fallback when first name is missing.

First name, else last name, else default

Cascading fallback logic for better personalization.

Confirmation Emails

Ensure that order confirmations, receipts, and status updates work even if optional fields are missing.

Order confirmation with order ID

Display order confirmation when order ID exists.

Download link for digital products

Conditional download links for digital product purchases.

Trial period days left

Show remaining trial days with fallback for expired trials.

Marketing

Create subject lines, headlines, and calls to action that fall back gracefully when data is missing.

Friendly subject line

Personalized subject lines with fallback.

Greeting with company name fallback

Dynamic greetings that adapt to available data.

Plan name with default

Display subscription plan with sensible default.

Product Recommendations

Build product suggestions from purchase history and preferences, with fallbacks when that data is missing.

Category-based recommendations

Show products based on last purchased category.

Purchase history fallback

Recommend based on previous purchases or show general promotions.

Seasonal promotion with personalization

Combine seasonal offers with personal data.

Links are the most common element in emails. The Liquid tag has two parts: a URL and a label. If you know HTML, it works like an <a href> (anchor) tag.

Required Attributes

  • Name
    url
    Type
    Url string
    Description

    Url you want the user to go to when they interact with the link.

  • Name
    hyperlink
    Type
    Label Text
    Description

    The text you want visible for the user to interact with.

A common gotcha we see is users including a full HTML <a href> tag, which causes the link to not work. For example, a user will use
<a href="https://example.com"></a> when they only need https://example.com.

Preview

Click Here!

Button

Buttons work the same as links but render with a button style. Use them for calls to action that need to stand out from the surrounding text.

The syntax is the same as links and follows the same rules. Avoid using HTML inside the URL.

  • Name
    url
    Type
    Url string
    Description

    Url you want the user to go to when they interact with the link.

  • Name
    hyperlink
    Type
    Label Text
    Description

    The text you want visible for the user to interact with.

  • Name
    color
    Type
    hexcode
    Description

    HEX code color for the button. You can read more about hex code colors here. Or find some great colors here.

Preview

Audio

Use the audio tag to embed an audio file in your email. Email clients that support playback show a player. Clients that don't get a direct link to the file instead.

  • Name
    url
    Type
    Url string
    Description

    Public url to the audio file for users to play.

  • Name
    type
    Type
    string
    Description

    Defines this link is an audio file for playback.

Preview

If your email client does not support playing audio click here to listen.

Images

The image tag displays an image in your email. It supports the standard HTML image options, including CSS classes, alt text, and dimensions.

  • Name
    url
    Type
    Url string
    Description

    Public url to the image file to display.

  • Name
    image_tag
    Type
    string
    Description

    comma separated list of options, supports in order css classes, id tag, alternate text, width in pixels, height in pixels

Preview

alt

Greeting

Builds a personalized greeting for the recipient, using their first name when it is available.

Liquid tags like this return plain text and inherit styling from the surrounding copy, so they match the rest of your template.

Preview

Hi Jesse,

Formatted Name

Builds the recipient's full name from the name fields on their profile.

Liquid tags like this return plain text and inherit styling from the surrounding copy, so they match the rest of your template.

Preview

John Doe

Gravatar Avatar

Uses the recipient's email to show their Gravatar avatar. You can learn more about Gravatar Avatars here.

In the case that the user does not have a Gravatar avatar a fallback image is provided.

Preview
bento_docs_feedback@bentonow.com John

Operators and Conditionals

If Conditional

Use an if conditional to show content based on subscriber data. For example, display a thank you message for subscribers who have completed a purchase. Subscribers who have not won't see it.

You can check any element in an if conditional: tags, the subscriber's city, or any tag or field you have created. By default the conditional content will not display.

You are not limited in what content can go inside the conditional.
It can be text links, buttons, images or full parts of your template.

Preview
This visitor has a 'customer' tag.

If/Else Conditional

An if/else conditional shows one block of content when the condition is true and another when it is false. Continuing the example above, subscribers who haven't purchased can see a CTA encouraging them to buy instead of a thank you.

Preview
You are in Sydney!

Operators

Operators let you use math and comparisons in conditionals. For example, offer a discount to subscribers with more than 10 orders, or to those who have spent over $100.

Math can be performed on any numeric field. For non-numeric fields, use count.

Preview
This visitor has ordered over 10 times!

Visitors Reference

Liquid TagResult
test@example.com
bento confirmation url
users unsubscribe url
control
Sydney
Australia
true/false
Subscriber tags
Male
John
Doe

Liquid Filters

Liquid filters transform the variables you pass them. Use them to append text, round numbers, do basic math, format data, and sort lists. For example, you can truncate a long description, convert a string to uppercase, or reformat a date. The filters below are supported in Bento. For the full specification, see the documentation here.

Append

Adds the specified string to the end of another string.


Capitalize

Makes the first character of a string capitalized and converts the remaining characters to lowercase.


Default

Sets a default value for any variable with no assigned value. default will show its value if the input is nil, false, or empty.


Divide By

Divides a number by another number.


The result is rounded down to the nearest integer (that is, the floor) if the divisor is an integer.


Downcase

Makes each character in a string lowercase. It has no effect on strings which are already all lowercase.


Minus

Subtracts a number from another number.


New Line Br

Inserts an HTML line break <br /> in front of each newline \n in a string.


Pluralize

Pluralizes a word based on a count.


Plus

Adds a number to another number.


Prepend

Adds the specified string to the beginning of another string.


Remove

Removes every occurrence of the specified substring from a string.


Replace

Replaces every occurrence of the first argument in a string with the second argument.


Round

Rounds a number to the nearest integer or, if a number is passed as an argument, to that number of decimal places.


Truncate

Shortens a string down to the number of characters passed as an argument. If the specified number of characters is less than the length of the string, an ellipsis (…) is appended to the string and is included in the character count.


Upper

Makes each character in a string uppercase. It has no effect on strings which are already all uppercase.


Helpers Reference

Environment Variables

Check your site's environment settings from inside a template. Each variable returns true or false.

Liquid TagResult
{{ ENV.webhooks }}true / false
{{ ENV.laravel }}true / false
{{ ENV.block_form_tracking }}true / false

Encryption and Hashing

These helpers encrypt or hash string values on demand, so you can generate a value for a user without storing it for retrieval. Useful for keeping PII out of plain text.

Liquid TagResult
{{ "secret_string" | md5 }}312f946cb92aaa541723382cda411c31
{{ "your secret string" | hmac_sha256: "key" }}63fa337d0a0e6520a12e223657d17184a5e2b131

Time

These helpers let you work with time dynamically. They matter most for large lists that send in batches over several hours. Each email calculates its time values when it is queued, so the content stays accurate even if a batch goes out later.

You can also use them to remind a subscriber that their birthday is coming up in a set number of days, or that it has been a set number of weeks since they last signed in or made a purchase.

All time responses are formatted time strings.
Liquid TagResult
{{ "2010-10-31" | advance_date_to_next: "monday" }}2010-11-01 00:00:00 +0000
{{ "2024-12-31" | days_until }}116
{{ "2024-12-31" | weeks_until }}16
{{ "2022-12-31" | weeks_since }}87
{{ "2022-12-31" | days_since }}614
{{ "2022-12-31" | at_midnight }}2022-12-31 00:00:00 +0000
{{ "2010-10-31" | in_time_zone: "America/Denver" | date: "%Y-%m-%d %H-%M-%S %z" }}2010-10-31 00-00-00 -0600
{{ "2010-10-31" | timestamp }}1288483200
{{ visitor.created_at | time_ago_in_words }}about 2 months

Money

Format money according to the currency assigned to the subscriber or visitor.

Liquid TagResult
{{ money.formatted }}$900.00 USD

Lottery Element

Randomly picks an element from the provided list. No weighting is applied, so each item has an equal chance of selection.

Supports only strings and you must provide the split delimiter
Liquid TagResult
{{ "Offer One||Offer 2||Offer 3" | split: "||" | pluck_at_random }}Offer 3

Broadcasts

These Liquid tags only work inside broadcasts.

Liquid TagResult
{{ subject }}Broadcast Subject
{{ name }}Name of the broadcast
{{ created_at }}Timestamp when broadcast was created

The timestamp returned by created_at can be reformatted using the time helpers. You can also adjust the timezone, for example to show the time in the subscriber's local time.

Sequences

These Liquid tags only work inside sequences.

Cancel the sequence

Creates a hyperlink that lets the subscriber stop the sequence they are in. This gives them an alternative to unsubscribing. Bento uses this in its own signup drip sequence.

Preview
No more emails like this!

Skip forward to the next email in the Sequence

Creates a link that skips the subscriber forward to the next email in the sequence. You can optionally redirect them to a specific URL.

When redirecting the URL, ensure it matches the domain of the author sending the emails.

Preview
Instantly get the next email.
Instantly get the next email with redirect.

Ecommerce

Render Last Cart

Displays the contents of the subscriber's last cart. Useful in reminder emails that encourage them to complete their purchase.

Preview

Apple Watch Ultra 2 - 799.00 USD - 1
49mm Indigo Alpine Loop - 99.00 USD - 1
49mm Orange Ocean Band - 99.00 USD - 1

Render Products

Displays a list of products.

This is available exclusively within flows.

This works like render cart but runs in flows and is not limited to the user's most recent cart.

Preview

Apple Watch Ultra 2 - 799.00 USD - 1
49mm Indigo Alpine Loop - 99.00 USD - 1
49mm Orange Ocean Band - 99.00 USD - 1

Abandoned Cart Checkout URL

Generates a personalized URL that takes the subscriber back to their shopping cart. Use it in reminder emails to make returning to the cart easy.

This provides the string URL, offering flexibility to create a full HTML hyperlink as needed.

This is available exclusively within flows.
Liquid TagResult
{{ abandoned_checkout_url | default: "https://example.com/cart" }}URL string

Stripe and Shopify

These Liquid tags integrate with Stripe and Shopify to generate coupon codes on demand.

This only returns a string value of the coupon code.

Shopify coupon

Generate a unique coupon code with Shopify.

  • Name
    coupon name
    Type
    string
    Description

    Name for the coupon code.

  • Name
    discount amount
    Type
    string
    Description

    Defines the discount amount.

  • Name
    discount type
    Type
    string
    Description

    Defines the type of discount valid options: fixed_amount percentage.

Preview

100OFF

Stripe coupon

Generate a unique coupon code with Stripe.

  • Name
    coupon name
    Type
    string
    Description

    Name for the coupon code.

  • Name
    discount %
    Type
    string
    Description

    Defines the discount amount.

  • Name
    length
    Type
    string
    Description

    In months how long the coupon will be valid.

Preview

TEST

Stripe billing portal link

Create a user-specific Stripe payment portal link.

Generates the URL; it does not create a full HTML link.
  • Name
    URL
    Type
    string
    Description

    The return URL for the billing portal session.

Preview

https://bentonow.com

External Data

Pull public data from sources outside of Bento directly into your templates.

RSS | JSON | HTML Parse

Define the URL of your data source, followed by the type option that tells Bento how to handle the data. Then use a loop to iterate over each item in the returned data.

Generates the string content. Requests must be public, and utilize a GET method.
Response data will be string data only.

  • Name
    URL
    Type
    string
    Description

    The URL of the public data source to fetch.

  • Name
    type
    Type
    string
    Description

    Supported data types are rss fetch_json youtube fetch_html

fetch_html has an additional parameter that allows you to define an HTML tag as the parent data wrapper, and what defines the children.

Preview

Milk

Eggs

Bread

Gmail Promo

This tag adds a promo annotation to your email, which Gmail can display in the Promotions tab alongside your subject line, often as a deal badge with a coupon code.

Whether the annotation displays is at Gmail's discretion.

Promo annotation

  • Name
    promo
    Type
    string
    Description

    What the promo is, often use the amount.

  • Name
    annotation
    Type
    string
    Description

    The supporting annotation to the promo, can be the coupon code.

Was this page useful?

Your answer helps us find docs that need work.