Benutzerdefinierte Liquid-Blöcke für gedruckte Belege

Du kannst einen benutzerdefinierten Liquid-Block verwenden, um dem Header oder der Fußzeile eines gedruckten Belegs deine eigenen Inhalte hinzuzufügen, wie z. B. Bestelldetails, Kundeninformationen, Produkteigenschaften, Metafelder und Barcodes.

Benutzerdefinierte Liquid-Blöcke werden auf gedruckten Belegen für abgeschlossene Online- und Point of Sale-Bestellungen gerendert. Sie werden nicht für Bestellungen gerendert, die den Offline-Checkout verwenden.

Du kannst einen benutzerdefinierten Liquid-Block über den visuellen Editor für Belege in deinem Shopify-Adminbereich hinzufügen. Die Werte, auf die du verweist, werden beim Drucken des Belegs aus den Belegdaten abgerufen. Der folgende Liquid-Code fügt dem Beleg beispielsweise die Bestellnotiz hinzu, wenn eine Notiz vorhanden ist:

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

Auf dieser Seite

Liquid-Syntaxregeln

Sieh dir die folgenden Syntaxregeln an, bevor du einen benutzerdefinierten Liquid-Block erstellst:

Variablennamen verwenden Kleinbuchstaben und Unterstriche, ein Format, das als snake_case bekannt ist. Verwende beispielsweise order.total_price, order.customer.display_name und order.line_items.
Geldwerte sind einfache Zahlen. Formatiere sie mit dem money-Filter, z. B. {{ order.total_price | money }}.
Sichere optionale Werte mit einer if-Anweisung ab, damit du keine leere Zeile druckst, z. B. {% if order.customer.email %}{{ order.customer.email }}{% endif %}.
Durchlaufe Listen mit einer for-Anweisung, z. B. {% for item in order.line_items %} ... {% endfor %}.
Einige Liquid-Tags werden nicht unterstützt. Du kannst assign, capture, include, render, raw, increment oder decrement nicht verwenden. Wenn dein Block ein nicht unterstütztes Tag verwendet, wird dein Beleg nicht gespeichert und dir wird ein Fehler angezeigt.
Ein benutzerdefinierter Liquid-Block kann bis zu 50 KB an Code enthalten.

HTML und CSS

Du kannst in einem benutzerdefinierten Liquid-Block grundlegendes HTML verwenden, um deine Inhalte zu strukturieren, z. B. <p>, <br>, <strong>, <em>, Überschriften, Listen und Links. Deine Inhalte verwenden die vorhandenen Schriftarten und Größen des Belegs.

Du kannst kein CSS verwenden, um das Aussehen eines Belegs zu ändern. <style>-Blöcke und style-Attribute werden nicht unterstützt, sodass ein benutzerdefinierter Liquid-Block Inhalte an anderer Stelle auf dem Beleg nicht umgestalten oder ausblenden kann. <script>-Tags, Ereignishandler wie onclick und javascript:-Links werden ebenfalls nicht unterstützt.

Wenn dein Block nicht unterstütztes HTML enthält, wird dein Beleg nicht gespeichert und dir wird ein Fehler angezeigt. Entferne das nicht unterstützte HTML und speichere dann erneut.

Variablen und Objekte

Ein benutzerdefinierter Liquid-Block kann auf die folgenden Objekte und Variablen verweisen. Einige Werte sind auf dem Standardbeleg nicht vorhanden, daher ist ein benutzerdefinierter Liquid-Block eine Möglichkeit, sie hinzuzufügen.

Top-Level-Variablen

Die folgenden Top-Level-Variablen sind in einem benutzerdefinierten Liquid-Block verfügbar.

Beschreibung der Top-Level-Variablen, die für einen benutzerdefinierten Liquid-Block verfügbar sind
Variable	Beschreibung
order	Die zu druckende Bestellung.
shop	Der Shop.
location	Der Einzelhandelsstandort.
settings	Die Anzeigeeinstellungen des Belegs, also die im Editor konfigurierten Umschalter.
purchased_gift_cards	Die bei dieser Bestellung gekauften Gutscheine.
staff_member_description	Die zugewiesenen Mitarbeiter:innen, wenn die Mitarbeiteranzeige aktiviert ist.
locale	Die Sprachvariante/das Gebietsschema des Belegs, wie z. B. en.
is_pickup	Ob die Bestellung eine Abholbestellung ist.
pickup_location	Der Abholort, falls zutreffend.

Bestellobjekt

Beschreibung des Bestellobjekts
Eigenschaft	Beschreibung
name	Der Bestellname, wie z. B. #1001.
created_at	Der Zeitstempel der Bestellung. Mit dem `date`-Filter verwenden.
note	Die Bestellnotiz.
subtotal_price	Die Zwischensumme. Mit dem `money`-Filter formatieren.
total_price	Der Gesamtbetrag. Mit dem `money`-Filter formatieren.
shipping_price	Der berechnete Versand. Mit dem `money`-Filter formatieren.
total_tip_received	Das gesamte Trinkgeld. Mit dem `money`-Filter formatieren.
balance_due	Der noch ausstehende Betrag. Mit dem `money`-Filter formatieren.
change_due	Das herausgegebene Wechselgeld. Mit dem `money`-Filter formatieren.
taxes_included	Ob die Steuer in den Preisen enthalten ist.
receipt_number	Die Belegnummer.
barcode_content	Der Inhalt, der in einem Barcode codiert werden soll.
qr_code_content	Der Inhalt, der in einem QR-Code codiert werden soll. Mit dem `qrcode`-Filter verwenden.
line_items	Die gekauften Artikel. Die Eigenschaften jedes Artikels sind im Objekt für Bestellpositionen aufgeführt.
transactions	Die Zahlungen. Die Eigenschaften jeder Zahlung sind im Transaktionsobjekt aufgeführt.
discounts	Die Rabatte auf Bestellebene. Die Eigenschaften jedes Rabatts sind im Rabattobjekt aufgeführt.
tax_lines	Die Steuerpositionen. Die Eigenschaften jeder Steuerposition sind im Steuerpositions-Objekt aufgeführt.
refunds	Die Rückerstattungen für die Bestellung.
shipping_address	Die Lieferadresse. Adresseneigenschaften werden im Adress-Objekt aufgelistet.
customer	Die Kundendetails, aufgelistet im Kunden-Objekt.
metafields	Die Metafelder der Bestellung.

Kunden-Objekt

Das order.customer -Objekt enthält die Kundendetails.

Beschreibung des Kunden-Objekts
Eigenschaft	Beschreibung
display_name	Der Anzeigename der Kund:in.
first_name	Der Vorname der Kund:in.
last_name	Der Nachname der Kund:in.
email	Die E-Mail-Adresse der Kund:in.
phone	Die Telefonnummer der Kund:in.
default_address	Die Standardadresse der Kund:in.
metafields	Die Kunden-Metafelder.

Bestellpositions-Objekt

Jeder Artikel in order.line_items enthält die folgenden Eigenschaften.

Beschreibung des Bestellpositions-Objekts
Eigenschaft	Beschreibung
name	Der Name des Produkts oder der Position.
variant_title	Die Variante, z. B. Groß/Blau.
sku	Die SKU.
vendor	Der Anbieter.
quantity	Die Menge.
price	Der Stückpreis. Formatierung mit dem `money`-Filter.
total_price	Die Gesamtsumme der Position. Formatierung mit dem `money`-Filter.
discounted_total_price	Die Gesamtsumme der Position nach Rabatten. Formatierung mit dem `money`-Filter.
discounted_unit_price	Der Stückpreis nach Rabatten. Formatierung mit dem `money`-Filter.
discounts	Die auf die Position angewendeten Rabatte.
selling_plan_name	Der Name des Abonnements oder Verkaufsplans, falls vorhanden.
staff_member_description	Die der Position zugewiesene Mitarbeiter:in.
custom_attributes	Die Eigenschaften der Position, auf die per Schlüssel zugegriffen wird.
product_metafields	Die Produkt-Metafelder, auf die per Schlüssel zugegriffen wird.
variant_metafields	Die Varianten-Metafelder, auf die per Schlüssel zugegriffen wird.

Transaktions-Objekt

Jede Zahlung in order.transactions enthält die folgenden Eigenschaften. Shop-Guthaben, das für die Bestellung ausgegeben wurde, wird als Zahlung mit dem Namen „Shop-Guthaben“ aufgeführt. Das verbleibende Shop-Guthaben der Kund:in ist nicht als Variable verfügbar.

Beschreibung des Transaktions-Objekts
Eigenschaft	Beschreibung
name	Der Zahlungsname, wie z. B. Visa, Barzahlung oder Shop-Guthaben.
payment_type	Der Code für die Zahlungsart.
amount	Der Betrag. Formatierung mit dem `money`-Filter.
kind	Die Art der Transaktion.
status	Der Transaktionsstatus.
credit_card_number	Die maskierte Kartennummer, falls zutreffend.
created_at	Der Zeitstempel der Transaktion.
additional_details	Zusätzliche Zeilen für Zahlungsdetails.

Shop-Objekt

Das shop -Objekt enthält die Shop-Details.

Beschreibung des Shop-Objekts
Eigenschaft	Beschreibung
name	Der Shop-Name.
domain	Die Shop-Domain.
currency	Die Shop-Währung.
id	Die Shop-ID.

Standort-Objekt

Das location -Objekt enthält die Details des Einzelhandelsstandorts.

Beschreibung des Standort-Objekts
Eigenschaft	Beschreibung
name	Der Name des Standorts.
address1	Die erste Adresszeile.
address2	Die zweite Adresszeile.
city	Die Stadt.
province	Die Provinz oder der Bundesstaat.
province_code	Der Code für Provinz oder Bundesstaat.
zip	Die Postleitzahl.
country	Das Land.
phone	Die Telefonnummer.
metafields	Die Standort-Metafelder.

Adress-Objekt

Eine Adresse, wie z. B. order.shipping_address oder order.customer.default_address, enthält die folgenden Eigenschaften.

Beschreibung des Adress-Objekts
Eigenschaft	Beschreibung
company	Der Name des Unternehmens.
name	Der Name der Empfänger:in.
address1	Die erste Adresszeile.
address2	Die zweite Adresszeile.
city	Die Stadt.
province	Die Provinz oder der Bundesstaat.
province_code	Der Code für Provinz oder Bundesstaat.
zip	Die Postleitzahl.
country	Das Land.
country_code	Der Ländercode.
phone	Die Telefonnummer.

Rabatt-Objekt

Jeder Rabatt in order.discounts oder item.discounts enthält die folgenden Eigenschaften.

Beschreibung des Rabatt-Objekts
Eigenschaft	Beschreibung
description	Die Beschreibung des Rabatts.
amount	Der Rabattbetrag. Formatierung mit dem `money`-Filter.
percentage	Der prozentuale Rabatt.

Steuerzeilen-Objekt

Jede Steuerzeile in order.tax_lines enthält die folgenden Eigenschaften.

Beschreibung des Steuerzeilen-Objekts
Eigenschaft	Beschreibung
title	Der Name der Steuer.
rate	Der Steuersatz als Dezimalzahl.
rate_percentage	Der Steuersatz in Prozent.
price	Der Steuerbetrag. Formatierung mit dem `money`-Filter.
taxable_amount	Der zu versteuernde Betrag. Formatierung mit dem `money`-Filter.

Gutschein-Objekt

Jeder Gutschein in purchased_gift_cards enthält die folgenden Eigenschaften.

Beschreibung des Gutschein-Objekts
Eigenschaft	Beschreibung
code	Der Gutscheincode.
masked_code	Der maskierte Gutscheincode.
balance	Das Gutschein-Guthaben. Mit dem `money`-Filter formatieren.
created_at	Der Zeitstempel des Gutscheins.
qr_code_content	Der Inhalt, der in einem QR-Code codiert werden soll.

Metafelder und Eigenschaften

Metafelder und Eigenschaften von Positionen gibt es in zwei Ausführungen.

Positions-Metafelder und -Eigenschaften sind mit Schlüsseln versehen. Greife über den Schlüssel direkt auf einen Wert zu:

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

Bestell- und Kunden-Metafelder sind Listen. Durchlaufe sie in einer Schleife:

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

Schlüssel werden in snake_case normalisiert. Auf einen Schlüssel wie Care Instructions oder careInstructions wird als care_instructions zugegriffen. Referenziere mit Schlüsseln versehene Werte immer in Kleinbuchstaben mit Unterstrichen.

Die Verfügbarkeit von Bestell- und Kunden-Metafeldern hängt davon ab, ob diese Metafelder im Datensatz vorhanden sind.

Liquid-Filter

Du kannst Filter verwenden, um die Informationen in deinem benutzerdefinierten Liquid-Block zu formatieren. Um einen Filter anzuwenden, füge ein Pipe-Zeichen (|) und dann den Filter innerhalb der Liquid-Ausgabe hinzu, z. B. {{ order.total_price | money }}.

Standard-Liquid-Filter funktionieren ebenfalls. Weitere Informationen zu Liquid-Filtern findest du in der Filter-Referenz.

Beschreibung der Filter, die für einen benutzerdefinierten Liquid-Block verfügbar sind
Filter	Beispiel	Beschreibung
money	{{ order.total_price \| money }}	Formatiert einen Betrag in der Belegwährung.
date	{{ order.created_at \| date: '%B %e, %Y' }}	Formatiert ein Datum oder eine Uhrzeit.
percent	{{ tax_line.rate \| percent }}	Formatiert eine Dezimalzahl als Prozentsatz, z. B. 0,2 als 20 %.
t	{{ 'receipt.total' \| t }}	Gibt eine übersetzte Bezeichnung zurück.
barcode	{{ order.barcode_content \| barcode }}	Rendert einen Barcode.
qrcode	{{ order.qr_code_content \| qrcode }}	Rendert einen QR-Code.

Beispiele für benutzerdefinierte Liquid-Blöcke

Die folgenden Beispiele fügen Inhalte hinzu, die sich nicht auf einer Standardvorlage für gedruckte Belege befinden.

Um die Bestellnotiz hinzuzufügen, falls eine vorhanden ist, verwende den folgenden Liquid-Code:

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

Um die SKU neben jedem Artikel hinzuzufügen, verwende den folgenden Liquid-Code:

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

Um eine Eigenschaft einer Position (z. B. eine Gravur) hinzuzufügen, verwende den folgenden Liquid-Code:

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

Um ein Produkt-Metafeld (z. B. Pflegehinweise) hinzuzufügen, verwende den folgenden Liquid-Code:

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

Um ein Kunden-Metafeld hinzuzufügen, verwende den folgenden Liquid-Code:

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

Um einen QR-Code hinzuzufügen, der zur Bestellung verlinkt, verwende den folgenden Liquid-Code:

{{ order.qr_code_content | qrcode }}