Merge Tags (HTML/CSS)

This article dives deep on the 3 categories of merge tags used within our Poplar platform. If you want to learn how to add merge tags to your creative please check out How to Convert a Static Design HTML

One unique feature of the Poplar platform is the capability to print dynamic mailers. You can personalize your postcards or letters just like you can in an email with any information you have on your customers like first name, past products purchased, and unique promo codes. This personalization allows you to create designs that are statistically more likely to get the recipient’s attention since they’re tailored to each individual.

Poplar offers a variety of flexible and creative ways to customize mailers based on different types of collected audience data.


Translating a static PDF design may sound intimidating, especially if you have little to no prior coding knowledge. Fortunately the process is usually as simple as pulling certain aspects of your static design together, re-saving them as one element, and embedding the URL within an .html file. There are a few key tools and elements to have in place before you begin:

  • Your original InDesign or Illustrator files
  • All image assets and fonts
  • Poplar’s HTML template files (found here)
  • A text editor such as Sublime or Visual Studio Code
  • A tool to preview your design as you code such as a browser window or

Since Poplar is converting an HTML file to PDF, the capabilities and best practices differ slightly from a web page which uses a multitude of behind-the-scenes tools and software to render in a browser. A browser can be used to preview your code design, but keep in mind certain elements, such as merge tags, may appear differently in the browser than they do when converted to PDF in the platform - this is why viewing the PDF proof generated by the platform is the best, most accurate way to check your work.

Personalizations can be broken down into four merge tag categories: Default, Promotion, Location-based, and Custom - all of which can be dynamically optimized by the use of Shopify’s Liquid Template language. All merge tag names must be formatted to exactly match the corresponding column header in your Mail File or Mailing API request.

Merge Tag Example

Default Merge Tags

Poplar will automatically populate default merge tags based on recipient data received via CSV upload or trigger integration. In your HTML creative, default merge tags are always preceded by recipient. to access the core recipient data in your mail file or API request.

The platform will NOT prompt you to set default values for default merge tags. This means that in the event of a blank value or mismatched data, your creative will print with a blank. Double check all column headers and Test all triggers before launch to ensure there are no merge tag data discrepancies.

Missing first name data will populate as Current Resident and will appear on your creative as such - if you are using the {{recipient.first_name}} merge tag, make sure first name is provided for every recipient.
See the Custom Merge Tag section for details on how to use first name with a default value...

Column Header or Key Merge Tag
full_name {{recipient. full_name}}
first_name {{recipient. first_name}}
last_name {{recipient. last_name}}
address_1 {{recipient. address_1}}
address_2 {{recipient. address_2}}
city {{recipient. city}}
state {{recipient. state}}
postal_code {{recipient. postal_code}}
email {{recipient. email}}
identifier {{recipient. identifier}}

Promotion Merge Tag

If you've created a Promotion and uploaded a list of unique codes, use a {{}} merge tag to pull in each code. Upon uploading creative, the platform will detect promotion. and prompt you to select your Promotion from a dropdown.


Location Based Merge Tags

Location based merge tags populate with data pulled from Saved Locations within your Poplar account. They are considered default merge tags, meaning the platform will NOT prompt you to set a default value to appear in the event of missing data. Location based merge tags provide a flexible and easy way to customize creative based on Geolocation settings.

Saved Location Field Merge Tag
Location Name {{location. name}}
Address 1 {{location. address_1}}
Address 2 {{location. address_2}}
City {{location. city}}
State {{location. state}} or {{location.state_name}}
Postal Code {{location. postal_code}}
Merge field 1 {{location. merge_field_1}}
Merge field 2 {{location. merge_field_2}}
Merge field 3 {{location. merge_field_3}}

There must be at least one (1) saved location under the geo-locations tab & the saved locations suppression must be toggled on under the campaign Suppressions tab before you upload an HTML creative including {{location.merge_tag}}. Click Saved Locations to learn more.

Custom Merge Tags

Poplar populates custom merge tag data by pulling from any additional column headers in your CSV Mail File, or any values present in the merge_tags object of your triggered API request. When HTML creative files are uploaded, the platform will scan for any custom merge tags present in your design and prompt you to set a default value. The default value will populate the custom merge tag in the event of a blank field or mismatched data in your CSV mail file or API request.

Uploading and storing files under Audiences will strip all custom merge tag values and extra column headers. To preserve custom merge tags for a One Time Send, drag & drop your CSV file directly into the platform during the launch process.

When adding custom merge tags to you HTML, make sure they are always preceded by custom. This is how the platform differentiates between default and custom merge tags. The following are common examples of custom merge tags:

Column Header or Webhook Field Merge Tag
image-url {{custom. image-url}}
last-purchase {{custom. last-purchase}}
loyalty-level {{custom. loyalty-level}}
first-name {{custom. first-name}}

If you don't have first name data for every recipient, you can create an additional custom merge tag named anything BUT first_name (ie. first-name or firstname). The platform will prompt you to set a default value (ie. "there" or "friend") to appear in the event of missing data.

QR Codes

The platform does not track QR code scans as part of attribution reporting. This is because scans can typically be tracked in the program used to generate your unique QR code URLs, such as Google Analytics.

Poplar also has the ability to render QR codes by using a Liquid tag to pass promotional data into the QR code configuration. The Liquid tag will return an image URL which can be used either as the src attribute of an <img> element or as the url for a background image.

The length of your URL affects the density of the QR code, therefore we recommend generating/using a shortened version of your URL to avoid scanning issues when printed.

QR Codes

Promotional data (codes, urls, etc.) must be created externally, as Poplar does not have the capability to generate or track promotional data.
Background Image Example
.qr-code {
 width: 200px;
 height: 200px;
 position: absolute;
 bottom: 100px;
 right: 100px;
 background-color: #fff;
 background-image: url({% qrcode text: '{{promotion.promo_code}}' %});
 background-size: 100%;


<div class="qr-code"></div>
Image Source Example
<img src="{% qrcode text: '{{custom.field-name}}' %}" class="qr-code" height="200" width="200" />


When setting up your QR code, the following parameters can be used in the configuration:

text required The text or URL for the QR code. Merge tags contained in this field are parsed.
color optional The foreground color for the QR code
bg optional The background color for the QR code
If the parameters are used as a merge tag, they do not currently have validation. For the color and bg, you will need to add the hex code without the # e.g., FF0000, not #FF0000. If the text field is empty, there will be no error.
Basic Example
{% qrcode text: '', color: '00a373', bg: 'ffffff' %}
Promotion Example

You can also reference promotion codes you imported into the Poplar platform.

{% qrcode text: '{{promotion.promo_code}}' %}
Custom Merge Tag Example
{% qrcode text: '{{custom.field-name}}' %}
Custom URL/string Example
{% qrcode text: '{{custom.field-name}}' %}
The QR code image returned is an SVG so that can be displayed at any size.

Liquid Logic

Poplar accepts the use of Shopify's Liquid Template language in HTML creatives. Liquid is an open-source templating language that lets you add nifty logic to dynamic data to make it even more flexible by using:

Objects Add high-level variability to dynamic data in your creative. All default and custom merge tags used in creative are classified as objects.

Tags Let you add conditional logic (using operators) to your messages. The most basic form is an if...else statement.

Filters Allow you to reformat and set consistent formatting ( ie uppercase, lowercase, or proper-case)

Use Cases & Code Snippets

There's no limit on the number of ways you can get creative with Liquid Templates; below are some sample use cases and code snippets to get you started. We highly recommend testing all your Liquid templates thoroughly in order to ensure they are error free!

Test your code in a Liquid Sandbox

Rolling Expiration Date

Add an expiration date to your creative that will always show 90 days from the time of print. The Liquid filter below creates a Unix timestamp, adds the number of seconds in 90 days and then reformats the date.

<!-- Example -->
If the postcard is printed on January 1, 2020 the output will automatically calculate and show 90 days in the future. 

<!-- Code -->
<div class="terms">
	Offer valid before {{ "now" | date: "%s" | plus: 7776000 | date: "%b %e, %Y" }}. Visit for additional terms.

<!-- Output -->

Offer valid before Mar 31, 2020. Visit for additional terms.
Character Casing

If your audience data contains some values that appear in all caps, lowercase, or a mix of both, Liquid can be used to ensure they appear consistently formatted in your creative design. Below is an example for how to make sure all first_name data appears in proper case, with the first letter uppercase and the rest lowercase.

<!-- Example -->
If audience data contains first_name "jane" or "JANE" you want to make sure it always appears as "Jane"

<!-- Code -->

<div class="dynamic-greeting">
	Hey {{ recipient.first_name | capitalize }}! Check out our new summer styles...

<!-- Output -->

	Hey Jane! Check out our new summer styles...

Variable Discount

Offer a variable discount based on a customer’s purchase history, average order value, lifetime value, etc. The Liquid tag below will use a custom merge tag to display a different message based on the purchase_history value listed in your audience data.

<!-- Example -->
A value greater than or equal to $200 for purchase_history would should read: 
"In celebration of your birthday, please take 20% off your next purchase..."

A value below $200 should read:
"In celebration of your special day, take $10 off your next purchase..."

<!-- Code -->

	We want to say thank you for your loyalty -

{% if custom.purchase_history >= "200.00" %}
	Enjoy 20% off your next purchase!

{% else %}

	Here's $10 off your next purchase of $100 or more! 
{% endif %}

<!-- Output for purchase_history >= $200 -->

	We want to say thank you for your loyalty -
	Enjoy 20% off your next purchase!

<!-- Output for purchase_history < $200 -->

	We want to say thank you for your loyalty -
	Here's $10 off your next purchase of $100 or more!

Terms & Conditions 

Dynamically alter legal text based on the recipient's city or state .

<!-- Example -->
Adjusting the legal text only on mailers sent to California to be CCPA compliant

<!-- Code -->

	Offer valid for first purchase.
{% if recipient.state == “CA” or recipient.state == "California" %}

	Under the California Consumer Privacy Act (CCPA)...

{% else %}

	Read our privacy policy at

{% endif %}

<!-- Output for California residents -->

	Offer valid for first purchase. Under the California Consumer Privacy Act (CCPA)...

<!-- Output for everywhere else -->

	Offer valid for first purchase. Read our privacy policy at

Behavior Dependent Images

Show a different product image based on characteristics related to the recipient’s most frequently purchased item. Below we have a custom merge tag called item-color, and the image shown in the creative features items of a similar color to those most frequently purchased.

<!-- Example -->
If a customer frequently buys red sunglasses, we want to show an image containing mostly red sunglasses.

If a customer frequently buys blue sunglasses, we want to show an image containing mostly blue sunglasses.

<!-- Code -->

{% if custom.item-color == "red" %}


{% elsif custom.item-color == "blue" %}


{% else %}


{% endif %} 
<!-- Output for Red -->

<img src="">

<!-- Output for Blue -->

<img src="">

<!-- Output for N/A -->

<img src="">

Reach out to for more use cases or assistance...