Custom Liquid blocks for printed receipts

Review the following syntax rules before you build a custom Liquid block:

• Variable names use lowercase letters and underscores, a format known as snake_case. For example, use order.total_price, order.customer.display_name, and order.line_items.
• Money values are plain numbers. Format them with the money filter, such as {{ order.total_price | money }}.
• Guard optional values with an if statement so that you don't print an empty line, such as {% if order.customer.email %}{{ order.customer.email }}{% endif %}.
• Loop over lists with a for statement, such as {% for item in order.line_items %} ... {% endfor %}.
• Some Liquid tags aren't supported. You can't use assign, capture, include, render, raw, increment, or decrement. If your block uses an unsupported tag, then your receipt won't save and you'll see an error.
• A custom Liquid block can contain up to 50 KB of code.

HTML and CSS

You can use basic HTML in a custom Liquid block to structure your content, such as <p>, <br>, <strong>, <em>, headings, lists, and links. Your content uses the receipt's existing fonts and sizes.

You can't use CSS to change how a receipt looks. <style> blocks and style attributes aren't supported, so that a custom Liquid block can't restyle or hide content elsewhere on the receipt. <script> tags, event handlers such as onclick, and javascript: links aren't supported either.

If your block contains unsupported HTML, then your receipt won't save and you'll see an error. Remove the unsupported HTML, and then save again.

A custom Liquid block can reference the following objects and variables. Some values aren't on the default receipt, so a custom Liquid block is one way to add them.

Top-level variables

The following top-level variables are available in a custom Liquid block.

order

shop

location

settings

purchased_gift_cards

staff_member_description

locale

is_pickup

pickup_location

Order object

name

created_at

note

subtotal_price

total_price

shipping_price

total_tip_received

balance_due

change_due

taxes_included

receipt_number

barcode_content

qr_code_content

line_items

transactions

discounts

tax_lines

refunds

shipping_address

customer

metafields

Customer object

The order.customer object contains the customer's details.

display_name

first_name

last_name

email

phone

default_address

metafields

Order line item object

Each item in order.line_items contains the following properties.

name

variant_title

sku

vendor

quantity

price

total_price

discounted_total_price

discounted_unit_price

discounts

selling_plan_name

staff_member_description

custom_attributes

product_metafields

variant_metafields

Transaction object

Each payment in order.transactions contains the following properties. Store credit spent on the order is listed as a payment named Store credit. The customer's remaining store credit balance isn't available as a variable.

name

payment_type

amount

kind

status

credit_card_number

created_at

additional_details

Shop object

The shop object contains the store's details.

name

domain

currency

id

Location object

The location object contains the retail location's details.

name

address1

address2

city

province

province_code

zip

country

phone

metafields

Address object

An address, such as order.shipping_address or order.customer.default_address, contains the following properties.

company

name

address1

address2

city

province

province_code

zip

country

country_code

phone

Discount object

Each discount in order.discounts or item.discounts contains the following properties.

description

amount

percentage

Tax line object

Each tax line in order.tax_lines contains the following properties.

title

rate

rate_percentage

price

taxable_amount

Gift card object

Each gift card in purchased_gift_cards contains the following properties.

code

masked_code

balance

created_at

qr_code_content

Metafields and line item properties come in two shapes.

Line item metafields and properties are keyed. Access a value directly by its key:

{{ item.product_metafields.care_instructions }}
{{ item.custom_attributes.engraving }}

Order and customer metafields are lists. Loop over them:

{% for m in order.metafields %}
  {{ m.namespace }}.{{ m.key }}: {{ m.value }}
{% endfor %}

Keys are normalized to snake_case. A key such as Care Instructions or careInstructions is accessed as care_instructions. Always reference keyed values in lowercase with underscores.

The availability of order and customer metafields depends on those metafields existing on the record.

You can use filters to format the information in your custom Liquid block. To apply a filter, add a pipe character, |, and then the filter inside the Liquid output, such as {{ order.total_price | money }}.

Standard Liquid filters also work. To learn more about Liquid filters, refer to the Filters reference.

money

{{ order.total_price | money }}

date

{{ order.created_at | date: '%B %e, %Y' }}

percent

{{ tax_line.rate | percent }}

t

{{ 'receipt.total' | t }}

barcode

{{ order.barcode_content | barcode }}

qrcode

{{ order.qr_code_content | qrcode }}

The following examples add content that isn't on a default printed receipt template.

To add the order note when one exists, use the following Liquid:

{% if order.note %}<p>Note: {{ order.note }}</p>{% endif %}

To add the SKU next to each item, use the following Liquid:

{% for item in order.line_items %}
  <p>{{ item.name }} — {{ item.sku }} ×{{ item.quantity }}</p>
{% endfor %}

To add a line item property, such as an engraving, use the following Liquid:

{% for item in order.line_items %}
  {% if item.custom_attributes.engraving %}
    <p>{{ item.name }} — Engraving: {{ item.custom_attributes.engraving }}</p>
  {% endif %}
{% endfor %}

To add a product metafield, such as care instructions, use the following Liquid:

{% for item in order.line_items %}
  {% if item.product_metafields.care_instructions %}
    <p>{{ item.name }}: {{ item.product_metafields.care_instructions }}</p>
  {% endif %}
{% endfor %}

To add a customer metafield, use the following Liquid:

{% for m in order.customer.metafields %}
  {% if m.key == 'loyalty_tier' %}<p>Loyalty tier: {{ m.value }}</p>{% endif %}
{% endfor %}

To add a QR code that links to the order, use the following Liquid:

{{ order.qr_code_content | qrcode }}