印刷用領収書のカスタムLiquidブロック

カスタムLiquidブロックを使用して、注文の詳細、お客様情報、商品プロパティ、メタフィールド、バーコードなど、独自のコンテンツを印刷用領収書のヘッダーやフッターに追加できます。

カスタムLiquidブロックは、完了したオンラインおよびPOSの注文の印刷用領収書にレンダリングされます。オフラインチェックアウトを使用する注文ではレンダリングされません。

管理画面の領収書のビジュアルエディタからカスタムLiquidブロックを追加できます。参照する値は、領収書の印刷時に領収書のデータから取得されます。たとえば、以下のLiquidコードを使用すると、メモが存在する場合に注文のメモが領収書に追加されます。

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

このページ内

Liquidの構文ルール

カスタムLiquidブロックを構築する前に、以下の構文ルールを確認してください。

変数名には小文字とアンダースコアを使用します。これはスネークケース (snake_case) と呼ばれる形式です。たとえば、order.total_price、order.customer.display_name、およびorder.line_itemsを使用します。
金額の値はプレーンな数値です。{{ order.total_price | money }}のように、moneyフィルターを使用してフォーマットします。
空行が印刷されないように、{% if order.customer.email %}{{ order.customer.email }}{% endif %}などのifステートメントを使用してオプションの値を保護します。
{% for item in order.line_items %} ... {% endfor %}などのforステートメントを使用して、リストに対してループ処理を行います。
一部のLiquidタグはサポートされていません。assign、capture、include、render、raw、increment、decrementは使用できません。サポートされていないタグがブロックで使用されている場合、領収書は保存されず、エラーが表示されます。
カスタムLiquidブロックには、最大 50 KBのコードを含めることができます。

HTMLとCSS

カスタムLiquidブロックでは、<p>、<br>、<strong>、<em>、見出し、リスト、リンクなど、基本HTMLを使用してコンテンツを構成できます。コンテンツには、領収書の既存のフォントとサイズが使用されます。

領収書の見た目を変更するためにCSSを使用することはできません。カスタムLiquidブロックが領収書の他の場所のコンテンツのスタイルを再設定したり、非表示にしたりできないように、<style>ブロックおよびstyle属性はサポートされていません。<script>タグ、onclickなどのイベントハンドラ、javascript:リンクもサポートされていません。

ブロックにサポートされていないHTMLが含まれている場合、領収書は保存されず、エラーが表示されます。サポートされていないHTMLを削除してから、もう一度保存してください。

変数とオブジェクト

カスタムLiquidブロックは、以下のオブジェクトと変数を参照できます。一部の値はデフォルトの領収書にはないため、追加方法の一つとしてカスタムLiquidブロックを使用できます。

トップレベルの変数

カスタムLiquidブロックでは、以下のトップレベルの変数が使用可能です。

カスタムLiquidブロックで使用可能なトップレベルの変数の説明
変数	説明
order	印刷中の注文。
shop	ストア。
location	店舗のロケーション。
settings	エディタで設定された切り替え項目である、領収書の表示設定。
purchased_gift_cards	この注文で購入されたギフトカード。
staff_member_description	スタッフの表示がオンになっている場合の担当スタッフ。
locale	enなどの領収書のロケール。
is_pickup	注文が受取注文であるかどうか。
pickup_location	該当する場合の受取ロケーション。

注文オブジェクト

注文オブジェクトの説明
プロパティ	説明
name	#1001などの注文名。
created_at	注文のタイムスタンプ。`date`フィルターとともに使用します。
note	注文のメモ。
subtotal_price	小計。`money`フィルターでフォーマットします。
total_price	合計。`money`フィルターでフォーマットします。
shipping_price	請求された配送料。`money`フィルターでフォーマットします。
total_tip_received	チップの合計。`money`フィルターでフォーマットします。
balance_due	未払い金額。`money`フィルターでフォーマットします。
change_due	渡されたお釣り。`money`フィルターでフォーマットします。
taxes_included	価格に税が含まれているかどうか。
receipt_number	領収書番号。
barcode_content	バーコードでエンコードするコンテンツ。
qr_code_content	QRコードでエンコードするコンテンツ。`qrcode`フィルターとともに使用します。
line_items	購入されたアイテム。各アイテムのプロパティは注文項目オブジェクトにリストされています。
transactions	決済。各決済のプロパティはトランザクションオブジェクトにリストされています。
discounts	注文レベルのディスカウント。各ディスカウントのプロパティはディスカウントオブジェクトにリストされています。
tax_lines	税項目。各税項目のプロパティは税項目オブジェクトにリストされています。
refunds	注文に対する返金。
shipping_address	配送先住所です。住所のプロパティは、address objectに記載されています。
customer	customer objectに記載されている、お客様の詳細です。
metafields	注文のメタフィールドです。

Customerオブジェクト

対象となる order.customer オブジェクトには、お客様の詳細が含まれています。

Customerオブジェクトの説明
プロパティ	説明
display_name	お客様の表示名です。
first_name	お客様の名です。
last_name	お客様の姓です。
email	お客様のメールアドレスです。
phone	お客様の電話番号です。
default_address	お客様のデフォルトの住所です。
metafields	お客様のメタフィールドです。

注文項目オブジェクト

対象の order.line_items 内の各項目には、以下のプロパティが含まれています。

注文項目オブジェクトの説明
プロパティ	説明
name	商品または項目の名前です。
variant_title	バリエーション (例: Lサイズ / 青) です。
sku	SKUです。
vendor	販売元です。
quantity	数量です。
price	単価です。`money`フィルターを使用してフォーマットします。
total_price	項目の合計です。`money`フィルターを使用してフォーマットします。
discounted_total_price	ディスカウント後の項目の合計です。`money`フィルターを使用してフォーマットします。
discounted_unit_price	ディスカウント後の単価です。`money`フィルターを使用してフォーマットします。
discounts	項目に適用されたディスカウントです。
selling_plan_name	サブスクリプションまたは販売計画の名前 (存在する場合) です。
staff_member_description	項目に関連付けられているスタッフです。
custom_attributes	キーでアクセスできる、項目のプロパティです。
product_metafields	キーでアクセスできる、商品のメタフィールドです。
variant_metafields	キーでアクセスできる、バリエーションのメタフィールドです。

Transactionオブジェクト

対象の order.transactions 内の各決済には、以下のプロパティが含まれています。注文で消費されたストアクレジットは、「Store credit」という名前の決済としてリストされます。お客様のストアクレジットの残高は、変数として利用できません。

Transactionオブジェクトの説明
プロパティ	説明
name	Visa、キャッシュ、ストアクレジットなどの決済名です。
payment_type	決済タイプのコードです。
amount	金額です。`money`フィルターを使用してフォーマットします。
kind	取引の種類です。
status	取引のステータスです。
credit_card_number	該当する場合、マスクされたカード番号です。
created_at	取引のタイムスタンプです。
additional_details	追加の決済詳細の行です。

Shopオブジェクト

対象となる shop オブジェクトには、ストアの詳細が含まれています。

Shopオブジェクトの説明
プロパティ	説明
name	ストア名です。
domain	ストアのドメインです。
currency	ストア通貨です。
id	ストアIDです。

Locationオブジェクト

対象となる location オブジェクトには、実店舗ロケーションの詳細が含まれています。

Locationオブジェクトの説明
プロパティ	説明
name	ロケーション名です。
address1	住所の1行目です。
address2	住所の2行目です。
city	市区町村です。
province	都道府県や州などです。
province_code	都道府県や州などのコードです。
zip	郵便番号です。
country	国です。
phone	電話番号です。
metafields	ロケーションのメタフィールドです。

Addressオブジェクト

対象となる order.shipping_address や order.customer.default_addressなどの住所には、以下のプロパティが含まれています。

Addressオブジェクトの説明
プロパティ	説明
company	会社名です。
name	受取人の名前です。
address1	住所の1行目です。
address2	住所の2行目です。
city	市区町村です。
province	都道府県や州などです。
province_code	都道府県や州などのコードです。
zip	郵便番号です。
country	国です。
country_code	国コードです。
phone	電話番号です。

Discountオブジェクト

対象の order.discounts や item.discounts 内の各項目には、以下のプロパティが含まれています。

Discountオブジェクトの説明
プロパティ	説明
description	ディスカウントの説明です。
amount	ディスカウント額です。`money`フィルターを使用してフォーマットします。
percentage	ディスカウントのパーセンテージです。

Tax lineオブジェクト

対象の order.tax_lines 内の各項目には、以下のプロパティが含まれています。

Tax lineオブジェクトの説明
プロパティ	説明
title	税のタイトルです。
rate	小数で表した税率です。
rate_percentage	パーセンテージで表した税率です。
price	税額です。`money`フィルターを使用してフォーマットします。
taxable_amount	課税対象額です。`money`フィルターを使用してフォーマットします。

Gift cardオブジェクト

対象の purchased_gift_cards 内の各項目には、以下のプロパティが含まれています。

Gift cardオブジェクトの説明
プロパティ	説明
code	ギフトカードのコード。
masked_code	マスクされたギフトカードのコード。
balance	ギフトカードの残高。`money` フィルターを使用してフォーマットします。
created_at	ギフトカードのタイムスタンプ。
qr_code_content	QRコードにエンコードするコンテンツ。

メタフィールドとプロパティ

メタフィールドと項目のプロパティには 2 つの形式があります。

項目のメタフィールドとプロパティにはキーが設定されています。キーから直接値にアクセスします。

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

注文とお客様のメタフィールドはリストです。これらをループ処理します。

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

キーはスネークケースに正規化されます。Care Instructions や careInstructions などのキーには、care_instructions としてアクセスします。キー付きの値を参照する際は、常にアンダースコアを使用した小文字を使用してください。

注文やお客様のメタフィールドを利用できるかどうかは、レコードにそれらのメタフィールドが存在するかどうかによって異なります。

Liquidフィルター

フィルターを使用して、カスタムLiquidブロック内の情報をフォーマットできます。フィルターを適用するには、Liquid出力内にパイプ文字 | を追加し、その後にフィルターを追加します (例: {{ order.total_price | money }})。

標準的なLiquidフィルターも機能します。Liquidフィルターについて詳しくは、フィルターのリファレンスを参照してください。

カスタムLiquidブロックで利用可能なフィルターの説明
フィルター	例	説明
money	{{ order.total_price \| money }}	金額を領収書の通貨でフォーマットします。
date	{{ order.created_at \| date: '%B %e, %Y' }}	日付または時刻をフォーマットします。
percent	{{ tax_line.rate \| percent }}	小数点をパーセンテージにフォーマットします (例: 0.2 を 20% として表示)。
t	{{ 'receipt.total' \| t }}	翻訳されたラベルを返します。
barcode	{{ order.barcode_content \| barcode }}	バーコードをレンダリングします。
qrcode	{{ order.qr_code_content \| qrcode }}	QRコードをレンダリングします。

カスタムLiquidブロックの例

以下の例では、デフォルトの印刷された領収書のテンプレートにはないコンテンツを追加します。

注文メモが存在する場合にそれを追加するには、以下のLiquidを使用します。

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

各アイテムの横に SKU を追加するには、以下のLiquidを使用します。

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

刻印などの項目プロパティを追加するには、以下のLiquidを使用します。

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

お手入れ方法などの商品のメタフィールドを追加するには、以下のLiquidを使用します。

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

お客様のメタフィールドを追加するには、以下のLiquidを使用します。

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

注文にリンクする QRコード を追加するには、以下のLiquidを使用します。

{{ order.qr_code_content | qrcode }}