How to add barcodes to your messages

You will learn

Learn how to use the {% barcode %} tag to generate Code 128 barcodes in your email, MMS, RCS, and WhatsApp messages. The barcode value can be a static string, a profile property, an event variable, or a Klaviyo coupon code.

Quick reference

Before you begin

The {% barcode %} tag works by generating a URL. When that URL is loaded (in a preview, an inbox, or a mobile device), it renders a PNG image of the barcode. This means the barcode image isn't created until the URL is actually fetched.

The {% barcode %} tag is supported in:

• Email
• MMS
• RCS
• WhatsApp

For mobile messages, you need the corresponding channel set up in your account. MMS barcode images can only be delivered where your sending number and the recipient’s country support MMS. See Understanding MMS image and GIF best practices for supported countries and number types.

Basic usage

The simplest way to use the barcode tag is:

{% barcode 'MyCode' %}

This produces a URL that returns a PNG image of a barcode. When scanned, the barcode contains the value MyCode.

You can customize the barcode by passing arguments to the tag. For example:

{% barcode 'MyCode' width=200 height=100 %}

See the arguments reference section below for all available options.

Using barcodes with different channels

Email

For email, you have two options for how the barcode renders:

Option 1: HTML mode (recommended for email)

Set mode=html to have the tag output an HTML <img> element directly. This is the simplest approach for including a barcode in an email.

{% barcode 'MyCode' mode=html %}

Place this tag in a text block or HTML block in the email template editor.

Option 2: URL mode

Leave the mode unset (or set mode=url) to output a URL. Use this option with an image block to control the image styling.

{% barcode 'MyCode' %}

1. Add an image block to your email template and select it.
2. Click Select image, then open the Dynamic image tab.
3. Paste the barcode tag into Dynamic variable or dynamic URL.
4. Click Save.

MMS

For MMS messages, add the barcode tag in the Dynamic image tab of the SMS/MMS editor, not in the text body.

1. Open your MMS message in the editor, select Content, and turn on Attachment.
2. Select Image, then click Select image. If the editor shows Media, select it and click Select media instead.
3. Go to the Dynamic image tab.
4. Paste your barcode tag into Dynamic variable or dynamic URL, for example:

{% barcode person.LoyaltyId %}

1. Click Save.

This follows the same process as adding any dynamic image to an MMS. For more details, see How to add a dynamic image to a text message.

RCS

For RCS messages, use mode=rcs to apply the default barcode and canvas dimensions for RCS images. Preview and test the message on your recipients’ device types before sending.

{% barcode 'MyCode' mode=rcs %}

1. In the RCS message editor, turn on the card’s Attachment section.
2. Select Image, then click Select image. If the editor shows Media, select it and click Select media instead.
3. Open Dynamic image, paste the barcode tag into Dynamic variable or dynamic URL, and click Save.

RCS defaults:

• Width: 600px
• Height: 300px
• Padded to: 1440x720px

These defaults follow Klaviyo's RCS image formatting recommendations. You can override them with custom width, height, padded_width, and padded_height values if needed.

WhatsApp

1. In the WhatsApp message editor, turn on Header and select Media.
2. Click Select media, then open the Dynamic image tab.
3. Paste your barcode tag into Dynamic variable or dynamic URL, for example:

{% barcode person.MembershipId %}

1. Click Save.

No special configuration or mode is needed for WhatsApp. The default mode=url works correctly.

Barcode tag arguments reference

Using barcodes with profile properties and event data

You can use profile properties or event variables as the barcode value to personalize it for each recipient. Recipients with the same value receive the same barcode.

Profile property examples:

{% barcode person.LoyaltyId %}
{% barcode person.email %}
{% barcode person.MembershipNumber %}

Event variable examples (for metric-triggered flows):

{% barcode event.Code %}
{% barcode event.OrderId %}

Handling missing values:

If a recipient doesn't have the property set, the barcode URL will be invalid and the image won't load. You have two options:

Option 1: Use a default filter to set a meaningful fallback value:

{% barcode person.BarcodeCode|default:'STORE-MEMBER' %}

Make sure the default is a value that makes sense if scanned. A generic placeholder like "fallback" would produce a scannable but useless barcode.

Option 2 (email): Use a conditional statement to hide the barcode entirely when the value is missing:

{% if person.BarcodeCode %}
  {% barcode person.BarcodeCode mode=html %}
{% endif %}

Combined example for email:

{% barcode person.LoyaltyId width=200 height=75 mode=html %}

Using barcodes with Klaviyo coupon codes

First, create or upload a coupon in Klaviyo. Set coupon=True and replace ShopifyCoupon in the example below with the coupon’s exact name in Klaviyo. Klaviyo assigns a coupon code to the recipient, or uses their existing valid code, and encodes that code in the barcode. See Getting started with coupon codes in Klaviyo for setup and coupon availability requirements.

{% barcode 'ShopifyCoupon' coupon=True %}

This works across all channels. For example, to send a coupon barcode via RCS:

{% barcode 'ShopifyCoupon' coupon=True mode=rcs %}

{% barcode person.CouponCode %}

Scaling and sizing

By default, the generated barcode image’s width and height are scaled by a factor of 3x. This means:

• A width of 100 renders at 300px actual width
• A height of 50 renders at 150px actual height

In mode=html, the email image is displayed at the tag’s original width and height. For example, width=100 height=50 generates a 300x150px image and sets its display size to 100x50px.

Exception: When mode=rcs, the scaling factor is 1x. This allows more precise control over the barcode dimensions to fit RCS image formatting requirements.

Padding values are not scaled. The padded_width and padded_height arguments represent the full canvas size in pixels. For URL and HTML modes, each must be at least 3 times the corresponding width or height. For mode=rcs, each must be at least the corresponding width or height because RCS uses 1x scaling. For example:

{% barcode 'Code' width=200 height=100 padded_width=700 padded_height=400 %}

Here, the barcode renders at 600x300px (200×3, 100×3) within a 700x400px padded canvas.

Maximum image size: The barcode service will not generate images larger than 4096x4096 pixels. This limit applies to the rendered size after scaling. For non-RCS barcodes (3x scaling), that means the maximum width argument is approximately 1365 (1365 × 3 = 4095px). For RCS barcodes (1x scaling), the maximum is 4096.

Width guidelines for long codes:

• For non-RCS barcodes: if your code exceeds 15 characters, increase the width beyond the default of 100 (which renders at 300px).
• For RCS barcodes: if your code exceeds 30 characters, increase the width beyond the default of 600px.

If the width is too narrow to encode the data, the barcode image will fail to generate.

Troubleshooting

Always preview before sending

Because the {% barcode %} tag produces a URL at render time and the image isn't generated until that URL is fetched, failures may not be apparent until you preview or send the message. Follow these steps to catch issues early:

1. Preview the message with a profile that has the required property and, for an event variable, the relevant event. If the barcode does not load, check the value, tag syntax, and dimensions before sending.
2. Scan the barcode. Use a barcode scanning tool (such as imagetotext.info/barcode-scanner) to verify the barcode encodes the expected value.
3. Send a test message to yourself before sending to your audience.

For coupon barcodes, an in-app preview uses the coupon name followed by -PREVIEW, not a redeemable coupon code. Sending a test message can use an available coupon code. Check the scanned value and test with the lengths of the codes you will actually send.

Common issues

The barcode image doesn't load

The most common cause is an empty barcode value. This happens when the tag references a profile property or event variable that the recipient doesn't have. For example:

{% barcode person.BarcodeCode %}

If the recipient has no BarcodeCode value, the generated URL will be missing the code, and the image won't render. To fix this, add a default filter. Replace the example fallback with a value that your scanner or point-of-sale system recognizes:

{% barcode person.BarcodeCode|default:'defaultCode' %}

The barcode image fails to generate but the URL looks correct

The barcode width is likely too narrow to encode all the data in your code. Try increasing the width value. As a rule of thumb:

• For non-RCS barcodes, codes over 15 characters need a width larger than the default 100 (300px rendered).
• RCS codes over 30 characters need a width larger than the default 600px.

The barcode doesn't appear in a text block (email)

Check whether the text block has show/hide logic applied. If a condition is hiding the block, the barcode won't render even if the tag is correct. Open the block's settings to verify.

Additional resources

• Getting started with coupon codes in Klaviyo — Learn how to create and manage coupon codes, including how to use the older {% barcode_code %} tag for coupon barcodes in email.
• How to add a dynamic image to a text message — Learn how to add dynamic images to MMS messages, including where to find the Dynamic image tab in the editor.
• Message personalization reference — Reference for all personalization tags available in Klaviyo, including profile properties, event variables, and filters.
• Understanding MMS image and GIF best practices — Best practices for image sizing and formatting in MMS messages.