Shopify Scripts API-Referenz

Skripte werden mit einer Ruby-API geschrieben, die dir ein hohes Maß an Kontrolle und Flexibilität bietet.

Plananforderung

Shopify Scripts und die Script Editor-App sind nur für Shops mit dem Shopify Plus-Plan verfügbar. Die Script Editor-App ist nicht mehr im Shopify App Store zum Download verfügbar.

Am 30. Juni 2026 werden Shopify Scripts entfernt und funktionieren dann nicht mehr. Wenn du weiterhin Support für deine bestehenden Anwendungsfälle für Shopify Scripts benötigst, musst du zu kompatiblen Ersatzlösungen mit Shopify Functions für deine bestehenden Zahlungs-, Versand- oder Positionsskripte wechseln. Erfahre mehr über den Wechsel von Shopify Scripts zu Shopify Functions.

Es gibt verschiedene Skripttypen. Einem Skript wird bei der Erstellung in der Script Editor-App ein Typ zugewiesen, je nachdem, mit welcher Skriptvorlage du beginnst:

Positionsskripte

Positionsskripte wirken sich auf die Positionen im Warenkorb aus und können Preise ändern sowie Rabatte gewähren. Diese Skripte werden ausgeführt, wenn eine Änderung am Warenkorb vorgenommen wird.

Positionsskripte, die ein Abonnement rabattieren, gelten nur für die erste Zahlung des Abonnements. Nachfolgende Zahlungen werden durch das Skript nicht rabattiert.

Einige Methoden können nur in Positionsskripten verwendet werden.

Versandskripte

Versandskripte interagieren mit dem Versand und können Versandarten ändern und Rabatte auf Versandtarife gewähren. Diese Skripte werden ausgeführt, wenn der Checkout die Seite mit den Versandoptionen erreicht.

Versandskripte, die den Versandtarif für ein Abonnement rabattieren, gelten nur für die erste Zahlung des Abonnements. Nachfolgende Zahlungen werden durch das Skript nicht rabattiert.

<p>Some methods <a href="#shipping-methods">can only be used in shipping scripts</a>.</p>

Zahlungsskripte

Zahlungsskripte interagieren mit Zahlungen und können Zahlungs-Gateways umbenennen, ausblenden und neu anordnen. Beachte, dass Zahlungsskripte nicht mit Zahlungs-Gateways interagieren, die vor dem Checkout-Bildschirm angezeigt werden, wie z. B. Apple Pay. Diese Skripte werden ausgeführt, wenn der Checkout die Zahlungsseite erreicht.

Einige Methoden können nur in Zahlungsskripten verwendet werden.

Allgemeine Methoden

Die folgenden Methoden können in jeder Art von Skript verwendet werden:

Eingabe

Eingabemethoden für Skripte

Methode	Rückgabetyp	Beschreibung
.cart	Cart	Gibt ein veränderbares Cart-Objekt zurück.
.locale	String	Gibt das Gebietsschema der Kundschaft zurück. Zum Beispiel en, fr oder pt-BR.

Cart

Das Cart-Objekt ist nur im Onlineshop verfügbar. Einige abgebrochene Checkouts haben Zugriff auf das Cart-Objekt. Wenn ein Checkout jedoch geschlossen wurde und Kund:innen anschließend den abgebrochenen Checkout aufrufen, werden sie zum vorausgefüllten Checkout weitergeleitet und das Cart-Objekt ist nicht mehr vorhanden. Das liegt daran, dass die Storefront durch die E-Mail zum abgebrochenen Checkout umgangen wurde.

Skriptmethoden, die das Cart-Objekt verwenden

Methode	Rückgabetyp	Beschreibung
.customer	Customer	Gibt den/die Inhaber:in des Warenkorbs zurück (sofern vorhanden).
.shipping_address	ShippingAddress	Gibt die Lieferadresse des/der Inhaber:in des Warenkorbs zurück (sofern vorhanden).
.discount_code	variiert	Gibt zurück: nil, wenn der Warenkorb keinen Rabattcode hat CartDiscount::FixedAmount, wenn der Warenkorb einen festen Rabattbetrag hat CartDiscount::Percentage, wenn der Warenkorb einen prozentualen Rabatt hat CartDiscount::Shipping, wenn der Warenkorb einen Versandrabatt hat Gibt einen einzelnen Rabattcode zurück (siehe Beschränkungen) discount_code ist vorhanden, wenn ein Rabatt auf den Warenkorb angewendet wurde. Dies bedeutet nicht zwangsläufig, dass sich der Preis des Warenkorbs ändert. Wenn beispielsweise ein Rabatt für Warenkörbe über 50 $ gilt und ein Skript den Preis des Warenkorbs unter 50 $ reduziert, ist der discount_code weiterhin vorhanden, der Preis des Warenkorbs ändert sich jedoch nicht. <p><a href="/manual/checkout-settings/script-editor/examples/vat-script">See an example of <code>discount_code</code></a>.</p> </td> </tr> <tr> <td scope="row">.line_items</td> <td><a href="#list">List</a>&lt;LineItem&gt;</td> <td>Returns a list containing the line items in the cart.</td> </tr> <tr> <td scope="row">.presentment_currency</td> <td><a href="#list">List</a>&lt;String&gt;</td> <td>Returns the customer's local (presentment) currency (in <a href="https://www.iso.org/iso-4217-currency-codes.html">ISO 4217</a> format). For example, USD. </td> </tr> <tr> <td scope="row">.subtotal_price</td> <td><a href="#money">Money</a></td> <td>Returns the subtotal price of the cart after line item discounts are applied but before discount codes are applied.</td> </tr> <tr> <td scope="row">.total_weight</td> <td><a href="https://shopify.dev/api/liquid/objects/line_item#line_item-grams">grams</a></td> <td>Returns the total weight of all the line items in the cart.</td> </tr>

CartDiscount::FixedAmount

Skriptmethoden, die das Objekt „CartDiscount::FixedAmount“ verwenden

Methode	Rückgabetyp	Beschreibung
.code	String	Gibt den Rabattcode zurück, der zur Anwendung des Rabatts verwendet wurde.
.amount	Money	Gibt den Geldbetrag des Rabatts zurück.
.reject({ message: String })	nil	Lehnt den auf den Warenkorb angewendeten Rabattcode ab. Eine message ist erforderlich.
.rejected?	Boolean	Gibt zurück, ob der Rabattcode abgelehnt wurde.

CartDiscount::Percentage

Skriptmethoden, die das Objekt „CartDiscount::Percentage“ verwenden

Methode	Rückgabetyp	Beschreibung
.code	String	Gibt den Rabattcode zurück, der zur Anwendung des Rabatts verwendet wurde.
.percentage	Dezimalzahl	Gibt den Prozentsatz des Rabatts zurück.
.reject({ message: String })	nil	Lehnt den auf den Warenkorb angewendeten Rabattcode ab. Eine message ist erforderlich.
.rejected?	Boolean	Gibt zurück, ob der Rabattcode abgelehnt wurde.

CartDiscount::Shipping

Skriptmethoden, die das CartDiscount::Shipping-Objekt verwenden

Methode	Rückgabetyp	Beschreibung
.code	String	Gibt den Rabattcode zurück, der zur Anwendung des Rabatts verwendet wurde.
.reject({ message: String })	nil	Lehnt den auf den Warenkorb angewendeten Rabattcode ab. Eine message ist erforderlich.
.rejected?	Boolean	Gibt zurück, ob der Rabattcode abgelehnt wurde.

Kunde

Skriptmethoden, die das Customer-Objekt verwenden

Methode	Rückgabetyp	Beschreibung
.id	Integer	Gibt die Kunden-ID zurück.
.email	String	Gibt die E-Mail-Adresse des/der Kund:in zurück.
.tags	List<Tag>	Gibt eine Liste von Strings zurück, die alle für eine:n Kund:in gesetzten Tags repräsentieren.
.orders_count	Integer	Gibt die Gesamtanzahl der Bestellungen zurück, die ein:e Kund:in aufgegeben hat.
.total_spent	Money	Gibt den Gesamtbetrag zurück, den der/die Kund:in für alle Bestellungen ausgegeben hat.
.accepts_marketing?	Boolean	Gibt zurück, ob der/die Kund:in Marketing akzeptiert.

Position

Skriptmethoden, die das LineItem-Objekt verwenden

Methode	Rückgabetyp	Beschreibung
.grams	grams	Gibt das Gesamtgewicht der Position zurück.
.line_price	Money	Der Preis der Position.
.discounted?	Boolean	Gibt zurück, ob der Preis einer Position durch ein Skript oder einen manuell angewendeten Rabatt rabattiert wurde. Die Verwendung von Rabattcodes beeinflusst den Rückgabewert nicht.
.properties	hash	Gibt die Eigenschaften zurück, die für diese Positionen angegeben wurden.
.variant	Variant	Gibt die spezifische Produktvariante zurück, die von der Position dargestellt wird.
.quantity	Integer	Gibt die Menge dieser Position zurück.
.selling_plan_id	Integer	Gibt die ID des Verkaufsplans für die Position zurück. Diese Methode ist nützlich, wenn der Shop Abonnements verkauft und du möchtest, dass das Skript erkennt, wann eine Produktvariante sold as a subscription wird.

List

Skriptmethoden, die das List-Objekt verwenden

Methode	Rückgabetyp	Beschreibung
.new	List	Erstellt ein neues Objekt, um eine Liste darzustellen.
.[]	Element or nil	Gibt das Element am angegebenen Index zurück.
.&	List	Gibt eine neue Liste mit den gemeinsamen Elementen beider Listen zurück, ohne Duplikate.
.delete_if	List	Löscht Elemente mithilfe eines optionalen Codeblocks. Siehe die Dokumentation für Ruby's delete_if method.
.empty?	Boolean	Gibt `true` zurück, wenn die Liste keine Elemente enthält.
.first	Element or nil	Gibt das erste Element oder `nil` zurück, wenn die Liste leer ist.
.index(*args, &block)	int or nil	Gibt den Index des ersten Elements der Liste zurück. Wenn anstelle eines Arguments ein Block angegeben wird, wird der Index des ersten Elements zurückgegeben, für das der Block `true` ist.
.rindex(*args, &block)	int or nil	Gibt den Index des letzten Elements der Liste zurück. Wenn anstelle eines Arguments ein Block angegeben wird, wird der Index des ersten Elements zurückgegeben, für das der Block `true` ist.
.last	Element or nil	Gibt das letzte Element oder `nil` zurück, wenn die Liste leer ist.
.length	int	Gibt die Anzahl der Elemente in der Liste zurück.
.size	int	Alias für „length“.
.each(*args, &block)	List	Ruft für jedes Element in der Liste einen Block auf und übergibt das Element als Parameter an den Block.

Lieferadresse

Skriptmethoden, die das ShippingAddress-Objekt verwenden

Methode	Rückgabetyp	Beschreibung
.name	String	Gibt den Namen der Person zurück, die der Lieferadresse zugeordnet ist.
.address1	String	Gibt den Straßenteil der Lieferadresse zurück.
.address2	String	Gibt das optionale Zusatzfeld der Lieferadresse zurück.
.phone	String	Gibt die Telefonnummer der Lieferadresse zurück.
.city	String	Gibt die Stadt der Lieferadresse zurück.
.zip	String	Gibt die Postleitzahl der Lieferadresse zurück.
.province	String	Gibt die Provinz/das Bundesland der Lieferadresse zurück.
.province_code	String	Gibt den abgekürzten Wert der Provinz/des Bundesstaates der Lieferadresse zurück.
.country_code	String	Gibt das Länderkürzel der Lieferadresse zurück.

Geld

Skriptmethoden, die das Money-Objekt verwenden

Methode	Rückgabetyp	Beschreibung
.derived_from_presentment(customer_cents:X)	Money	Wandelt einen Betrag (in Cent) von der lokalen Währung des/der Kund:in (Darstellungswährung) in die Währung deines Shops um. Diese Methode akzeptiert den Parameter customer_cents, der eine Zahl in Cent akzeptiert. Zum Beispiel Money.derived_from_presentment(customer_cents: 500).
.new	Money	Erstellt ein neues Objekt, das einen Preis darstellt.
.zero	Money	Erstellt ein neues Objekt mit einem Preis von Null.
+	Money	Addiert zwei Money-Objekte.
-	Money	Subtrahiert ein Money-Objekt von einem anderen.
*	Money	Multipliziert ein Money-Objekt mit einer Zahl.

Money-Beispiele

Money.new(cents: 1000)

Erstellt ein Money-Objekt, das 1000 Cent oder 10 $ darstellt.

Money.new(cents: 100) * 50

Erstellt ein Money-Objekt, das 1 $ darstellt, und multipliziert diesen Betrag dann mit 50. Gibt ein Money-Objekt zurück, das 50 $ darstellt.

Variante

Skriptmethoden, die das Variant-Objekt verwenden

Methode	Rückgabetyp	Beschreibung
.id	Integer	Gibt die ID-Nummer der Variante zurück.
.price	Money	Gibt den Stückpreis der Variante zurück.
.product	Produkt	Gibt das zugehörige Produkt der Variante zurück.
.skus	Liste<String>	Gibt die Artikelnummern (SKUs) der Variante zurück, die häufig für die Nachverfolgung des Inventars verwendet werden.
.title	String	Gibt den Titel der Variante zurück.

Produkt

Skriptmethoden, die das Product-Objekt verwenden

Methode	Rückgabetyp	Beschreibung
.id	Integer	Gibt die ID-Nummer des Produkts zurück.
.gift_card?	Boolean	Gibt zurück, ob das Produkt ein Gutschein ist.
.tags	List<Tag>	Gibt eine Liste von Strings zurück, die die für dieses Produkt festgelegten Tags darstellen.
.product_type	String	Eine Kategorisierung, mit der ein Produkt getaggt werden kann und die häufig zum Filtern und Suchen verwendet wird.
.vendor	String	Gibt den Anbieter dieses Produkts zurück.

Kernel

Kernel ist ein Ruby-Modul, das in jeder Klasse enthalten ist. Daher sind seine Methoden für jedes Objekt verfügbar. Diese Methoden verhalten sich auf die gleiche Weise wie globale Funktionen in anderen Sprachen.

Skriptmethoden, die das Kernel-Objekt verwenden

Methode	Rückgabetyp	Beschreibung
.exit	keine	Beendet die Ausführung des aktuellen Skripts ohne Fehler. Wenn dies ausgeführt wird, bevor Output.cart etwas zugewiesen wird, hat das Skript keine Auswirkungen. Dies ist eine nützliche Methode, um Skripts zu beenden, zum Beispiel, wenn Kund:innen nicht berechtigt sind, das Skript auszuführen.

Kernel-Beispiel

customer = Input.cart.customer
if customer && customer.email.end_with?("@mycompany.com")
  # Employees are not eligible for this promotion.
  exit
end

Positionsmethoden

Die folgenden Methoden können nur in Positionsskripts verwendet werden:

Cart

Skriptmethoden, die das Cart-Objekt in Positionsskripts verwenden

Methode	Rückgabetyp	Beschreibung
.subtotal_price_was	Money	Gibt die Zwischensumme des Warenkorbs zurück, bevor Rabatte angewendet wurden.
.subtotal_price_changed?	Boolean	Gibt zurück, ob sich die Zwischensumme geändert hat.

Position

Skriptmethoden, die das LineItem-Objekt in Positionsskripts verwenden

Methode	Rückgabetyp	Beschreibung
.change_line_price(Money new_price, { message: String })	Money	Ändert den Preis der Position auf den angegebenen Betrag. Eine message ist erforderlich. new_price muss niedriger sein als der aktuelle Preis.
.original_line_price	Money	Gibt den ursprünglichen Preis der Position zurück, bevor Skripts und Rabatte angewendet wurden.
.line_price_was	Money	Gibt den Preis der Position zurück, bevor durch das aktuelle Skript Änderungen vorgenommen wurden.
.line_price_changed?	Boolean	Gibt zurück, ob sich der Preis der Position geändert hat.
.change_properties(hash new_properties, { message: String })	hash	Legt neue Eigenschaften für eine Position fest. Der ursprüngliche Eigenschaften-Hash wird in properties_was gespeichert und der an die Methode übergebene Eigenschaften-Hash wird zu den neuen Eigenschaften für die Position.
.properties_was	hash	Gibt den ursprünglichen Eigenschaften-Hash der Position zurück, bevor Änderungen vorgenommen wurden.
.properties_changed?	Boolean	Gibt zurück, ob die Eigenschaften für die Position geändert wurden.
.split({ take: Integer })	Position	Teilt eine Position in zwei Positionen auf. take gibt an, welche Menge aus der ursprünglichen Position entfernt werden soll, um die neue Position zu erstellen.

.split-Beispiel

Dieses Beispielskript teilt eine Position namens original_line_item in zwei Positionen auf. Die neue Position hat die Menge 1 (angegeben durch take: 1). Das Skript wendet dann einen reduzierten Preis auf die neue Position mit der Meldung „Third hat for 5 dollars“ an.

if original_line_item.quantity >= 3
  new_line_item = original_line_item.split(take: 1)
  new_line_item.change_line_price(Money.new(cents: 500), message: "Third hat for 5 dollars")
  cart.line_items << new_line_item
end

Variante

Skriptmethoden, die das Variant-Objekt in Positionsskripts verwenden

Methode	Rückgabetyp	Beschreibung
.compare_at_price	Money	Gibt den Vergleichspreis der Variante zurück. Gibt nil zurück, wenn die Variante keinen Vergleichspreis hat.

Versandmethoden

Die folgenden Methoden können in Versandskripts verwendet werden:

Eingabe

Skriptmethoden, die das Input-Objekt in Versandskripts verwenden

Methode	Rückgabetyp	Beschreibung
.shipping_rates	ShippingRateList	Gibt eine Liste aller Versandtarife zurück.

ShippingRateList

Skriptmethoden, die das ShippingRateList-Objekt in Versand-Skripten verwenden

Methode	Rückgabetyp	Beschreibung
.delete_if	ShippingRateList	Löscht Versandtarife mithilfe eines optionalen Code-Blocks. Weitere Informationen findest du in der Dokumentation zur delete_if-Methode von Ruby.
.sort!	ShippingRateList	Sortiert die Versandtarife mithilfe des Vergleichsoperators oder eines optionalen Code-Blocks. Weitere Informationen findest du in der Dokumentation zur sort!-Methode von Ruby.
.sort_by!	ShippingRateList	Sortiert die Versandtarife mithilfe eines optionalen Code-Blocks. Weitere Informationen findest du in der Dokumentation zur sort_by!-Methode von Ruby.

ShippingRate

Skriptmethoden, die das ShippingRate-Objekt in Versand-Skripten verwenden

Methode	Rückgabetyp	Beschreibung
.code	String	Gibt den Code des Versandtarifs zurück.
.markup	Money	Gibt den Aufschlag für einen Versandtarif zurück, falls zutreffend.
.name	String	Gibt den Namen des Versandtarifs zurück. Er kann mit der change_name-Methode geändert werden.
.price	Money	Gibt den Preis des Versandtarifs zurück.
.source	String	Gibt die Quelle (den Versanddienstleister) zurück, die dem Versandtarif zugeordnet ist, falls relevant. Sie kann nicht geändert werden.
.change_name(String new_name)	String	Ändert den Namen (maximal 255 Zeichen) des Versandtarifs. Es ist nicht möglich, die Quelle zu ändern, zu löschen oder auszublenden.
.apply_discount(Money discount, { message: String })	Money	Wendet einen Rabatt in Höhe des angegebenen festen Betrags an. Der Preis kann nicht unter 0 reduziert werden. Eine Nachricht ist erforderlich.
.phone_required?	Boolean	Gibt true zurück, wenn für den Versandtarif eine Telefonnummer erforderlich ist, oder false, wenn keine Telefonnummer erforderlich ist.

Zahlungsmethoden

Die folgenden Methoden können in Zahlungs-Skripten verwendet werden:

Eingabe

Skriptmethoden, die das Input-Objekt in Zahlungs-Skripten verwenden

Methode	Rückgabetyp	Beschreibung
.payment_gateways	PaymentGatewaysList	Gibt eine Liste aller Zahlungs-Gateways im Shop zurück.

PaymentGatewayList

Skriptmethoden, die das PaymentGatewayList-Objekt in Zahlungs-Skripten verwenden

Methode	Rückgabetyp	Beschreibung
.delete_if	PaymentGatewayList	Löscht Zahlungs-Gateways mithilfe eines optionalen Code-Blocks. Weitere Informationen findest du in der Dokumentation zur delete_if-Methode von Ruby.
.sort!	PaymentGatewayList	Sortiert die Zahlungs-Gateways mithilfe des Vergleichsoperators oder eines optionalen Code-Blocks. Weitere Informationen findest du in der Dokumentation zur sort!-Methode von Ruby.
.sort_by!	PaymentGatewayList	Sortiert die Zahlungs-Gateways mithilfe eines optionalen Code-Blocks. Weitere Informationen findest du in der Dokumentation zur sort_by!-Methode von Ruby.

PaymentGateway

Methode	Rückgabetyp	Beschreibung
.name	String	Gibt den Namen des Zahlungs-Gateways zurück.
.enabled_card_brands	Liste<String>	Wenn das Zahlungs-Gateway Kreditkarten unterstützt, wird eine Liste der Kreditkartentypen zurückgegeben, die der Shop akzeptiert. Wenn das Gateway keine Kreditkarten unterstützt, wird eine leere Liste zurückgegeben.
.change_name(String new_name)	String	Ändert den Namen des Zahlungs-Gateways. Zahlungs-Gateways mit Logos können nicht umbenannt werden.

Beispiele

Im folgenden Beispiel für ein Positions-Skript gilt: Wenn ein:e Kund:in ein Produkt bestellt, das kein Gutschein ist, wird der Preis des Produkts um 9 $ reduziert. Außerdem wird der Gesamtbetrag angezeigt, den der/die Kund:in bei allen Besuchen in deinem Shop ausgegeben hat:

customer = Input.cart.customer
Input.cart.line_items.each do |line_item|
  product = line_item.variant.product
  next if product.gift_card?
  line_item.change_line_price(line_item.line_price - Money.new(cents: 900), message: customer.total_spent)
end

Output.cart = Input.cart

Mehr Informationen

Mehr Informationen über:

• Die Grundlagen von Ruby
• Erstellen von Skripten
• Testen und Debuggen deiner Skripte
• Aktualisieren deiner Liquid-Vorlagen für Skripte
• Shopify Scripts