Shopify Scripts-API-Referenz

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

Es gibt verschiedene Skripttypen. Einem Skript wird bei der Erstellung in der Script Editor-App basierend auf der ausgewählten Skriptvorlage ein Typ zugewiesen:

Einzelartikel-Skripte

Skripte für Einzelartikel wirken sich auf Einzelartikel im Warenkorb aus und können Preise ändern oder Rabatte gewähren. Diese Skripte werden ausgeführt, wenn eine Änderung am Warenkorb vorgenommen wird.

Einzelartikel-Skripte, die einen Rabatt auf Abonnementgebühren anwenden, gelten ausschließlich für die erste Zahlung der Abonnementgebühren. Das Skript wendet keinen Rabatt auf nachfolgende Zahlungen an.

Einige Methoden können nur in Einzelartikel-Skripten verwendet werden.

Versand-Skripte

Skripte für den Versand interagieren mit dem Versand, und können Versandmethoden ändern und Rabatte auf Versandkosten anwenden. Diese Skripte werden ausgeführt, wenn der Checkout die Seite mit den Versandoptionen erreicht.

Versand-Skripte, die einen Rabatt auf Versandgebühren anwenden, gelten ausschließlich für die erste Zahlung der Abonnementgebühren. Das Skript wendet keinen Rabatt auf nachfolgende Zahlungen an.

Einige Methoden können nur in Versand-Skripten verwendet werden.

Zahlungsskripte

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

Einige Methoden können nur in Zahlungs-Skripten verwendet werden.

Auf dieser Seite

Allgemeine Methoden

Die folgenden Methoden können in jedem Skripttyp verwendet werden:

Eingabe

Skript-Eingabemethoden
Art	Rückgabetyp	Beschreibung
.cart	Warenkorb	Gibt ein veränderbares Warenkorbobjekt zurück.
.locale	String	Gibt das Gebietsschema des Kunden an. Zum Beispiel `en`, `fr` oder `pt-BR`.

Warenkorb

Das Warenkorbobjekt ist nur für den Onlineshop-Kanal verfügbar. Einige abgebrochene Checkouts haben Zugriff auf das Warenkorbobjekt. Wenn ein Checkout allerdings geschlossen wurde und der Kunde dann den abgebrochenen Checkout aufruft, wird dieser direkt zum vorab ausgefüllten Checkout weitergeleitet und das Warenkorbobjekt existiert nicht mehr. Das liegt daran, dass der Kunde durch die E-Mail mit der Mitteilung über den abgebrochenen Checkout die eigentliche Storefront umgeht.

Skript-Methoden, die das Cart-Objekt verwenden
Art	Rückgabetyp	Beschreibung
.customer	Kunde	Gibt den Inhaber des Warenkorbs aus (falls vorhanden).
.shipping_address	Lieferadresse	Gibt die Lieferadresse des Besitzers des Warenkorbs aus (falls vorhanden).
.discount_code	variiert	Rückgaben: `nil` wenn der Warenkorb keinen Rabattcode enthält `CartDiscount::FixedAmount` wenn der Warenkorb einen festen Rabattbetrag enthält `CartDiscount::Percentage` wenn der Warenkorb einen prozentualen Rabatt enthält `CartDiscount::Shipping` wenn der Warenkorb einen Versandrabatt enthält Gibt einen einzelnen Rabattcode zurück (siehe Einschränkungen) `discount_code` wird angezeigt, wenn ein Rabatt auf den Warenkorb angewendet wurde. Dies bedeutet nicht zwangsläufig, dass sich der Preis des Inhalts im Warenkorb ändert. Wenn beispielsweise ein Rabatt für Warenkörbe mit einem Inhalt von über 50 EUR gilt und ein Skript den Preis auf unter 50 EUR reduziert, ist `discount_code` zwar weiterhin vorhanden, der Preis des Inhalts im Warenkorb ändert sich jedoch nicht. Schaue dir ein Beispiel für `discount_code` an.
.line_items	Liste <Einzelartikel>	Gibt eine Liste mit den Einzelartikeln im Warenkorb aus.
.presentment_currency	Liste<String>	Gibt die Landeswährung (Darstellungswährung) des Kunden (im Format ISO 4217) aus. Zum Beispiel: USD.
.subtotal_price	Money	Gibt die Zwischensumme des Warenkorbs aus, einschließlich Einzelartikel-Rabatten aber ohne angewendete Rabattcodes.
.total_weight	Gramm	Gibt das Gesamtgewicht aller Einzelartikeln im Warenkorb aus.

Warenkorbrabatt::FesterBetrag

Skript-Methoden, die das CartDiscount:: FixedAmount-Objekt verwenden
Art	Rückgabetyp	Beschreibung
.code	String	Gibt den Rabattcode an, der für diesen Rabatt angewandt wurde.
.amount	Money	Gibt den Geldbetrag des Rabattes aus.
.reject({ message: String })	Null	Lehnt den Rabattcode ab, der auf den Warenkorb angewendet wurde. Eine `Nachricht` ist erforderlich.
.rejected?	Boolescher Wert	Meldet, ob der Rabattcode abgelehnt wurde.

Warenkorbrabatt::Prozentsatz

Skript-Methoden, die das CartDiscount::P ercentage-Objekt verwenden
Art	Rückgabetyp	Beschreibung
.code	String	Gibt den Rabattcode an, der für diesen Rabatt angewandt wurde.
.percentage	Dezimal	Gibt den Prozentsatz des Rabattes aus.
.reject({ message: String })	Null	Lehnt den Rabattcode ab, der auf den Warenkorb angewendet wurde. Eine `Nachricht` ist erforderlich.
.rejected?	Boolescher Wert	Meldet, ob der Rabattcode abgelehnt wurde.

CartDiscount::Shipping

Skript-Methoden, die das CartDiscount:: Shipping-Objekt verwenden
Art	Rückgabetyp	Beschreibung
.code	String	Gibt den Rabattcode an, der für diesen Rabatt angewandt wurde.
.reject({ message: String })	Null	Lehnt den Rabattcode ab, der auf den Warenkorb angewendet wurde. Eine `Nachricht` ist erforderlich.
.rejected?	Boolescher Wert	Meldet, ob der Rabattcode abgelehnt wurde.

Kunde

Skript-Methoden, die das Customer-Objekt verwenden
Art	Rückgabetyp	Beschreibung
.id	Ganze Zahl	Gibt die ID-Nummer der Kunden aus.
.email	String	Gibt die E-Mail-Adresse der Kunden aus.
.tags	Liste<Tag>	Gibt eine Liste von Strings aus, die alle für einen Kunden festgelegte Tags darstellen.
.orders_count	Ganze Zahl	Gibt die Gesamtzahl der Bestellungen aus, die ein Kunde aufgegeben hat.
.total_spent	Money	Gibt den Gesamtbetrag aus, den der Kunde für alle Bestellungen ausgegeben hat.
.accepts_marketing?	Boolescher Wert	Gibt an, ob der Kunde Marketing akzeptiert.

Position

<tdgrams

Skript-Methoden, die das LineItem-Objekt verwenden
Art	Rückgabetyp	Beschreibung
.grams	Gibt das Gesamtgewicht des Einzelartikels aus.
.line_price	Money	Der Preis des Einzelartikels.
.discounted?	Boolescher Wert	Gibt aus, ob der Preis einer Position durch ein Skript oder einen manuell angewendeten Rabatt reduziert wurde. Die Verwendung von Rabattcodes hat keinen Einfluss auf den Rückgabewert.
.properties	hash	Gibt die Eigenschaften aus, die für diese Einzelartikel angegeben wurden.
.variant	Variante	Gibt die bestimmte Produktvariante dieses Einzelartikels aus.
.quantity	Ganze Zahl	Gibt die Menge dieses Einzelartikels aus.
.selling_plan_id	Ganze Zahl	Gibt die ID des Verkaufsplans der Position aus. Diese Methode ist nützlich, wenn der Shop Abonnements verkauft und du möchtest, dass das Skript erkennt, wann eine Produktvariante als Abonnement verkauft wird.

Liste

Skript-Methoden, die das List-Objekt verwenden
Art	Rückgabetyp	Beschreibung
.new	Liste	Erstellt ein neues Objekt zur Darstellung einer Liste.
.[]	Element oder nil	Gibt das Element zum angegebenen Index zurück.
.&	Liste	Gibt eine neue Liste zurück, die Elemente enthält, die den beiden Listen gemeinsam sind und keine Duplikate enthalten.
.delete_if	Liste	Elemente mithilfe eines optionalen Codeblocks löschen. Siehe die Dokumentation für die `delete_if`-Methode in Ruby.
.empty?	Boolescher Wert	Gibt `true` aus, wenn die Liste keine Elemente enthält.
.first	Element oder nil	Gibt das erste Element der Liste aus. Ist die Liste leer, wird `nil` ausgegeben.
.index(*args, &block)	int oder nil	Gibt den Index des ersten Elements der Liste aus. Wenn ein Block anstelle eines Arguments angegeben wird, wird der Index des ersten Elements ausgegeben, für das der Block wahr ist.
.rindex(*args, &block)	int oder nil	Gibt den Index des letzten Elements der Liste zurück. Wenn ein Block anstelle eines Arguments angegeben wird, wird der Index des ersten Elements zurückgegeben, für das der Block wahr ist.
.last	Element oder nil	Gibt das letzte Element aus oder `nil`, falls die Liste leer ist.
.length	int	Gibt die Anzahl der Elemente in der Liste aus.
.size	int	Alias für length.
.each(*args, &block)	Liste	Ruft für jedes Element in der Liste einen Block einmal auf und übergibt das Element als Parameter an den Block.

Lieferadresse

Skript-Methoden, die das ShippingAddress-Objekt verwenden
Art	Rückgabetyp	Beschreibung
.name	String	Gibt den Namen der Person aus, die mit der Lieferadresse verknüpft ist.
.address1	String	Gibt den Straßenadressabschnitt der Lieferadresse aus.
.address2	String	Gibt das optionale zusätzliche Feld des Abschnitts der Straßenadresse der Lieferadresse aus.
.phone	String	Gibt die Telefonnummer der Lieferadresse aus.
.city	String	Gibt die Stadt der Lieferadresse aus.
.zip	String	Gibt die Postleitzahl der Lieferadresse aus.
.province	String	Gibt das Bundesland/den Kanton der Lieferadresse aus.
.province_code	String	Gibt den abgekürzten Wert der Provinz / des Bundesstaates der Lieferadresse aus.
.country_code	String	Gibt den abgekürzten Wert des Landes der Lieferadresse aus.

Money

Skript-Methoden, die das Money-Objekt verwenden
Art	Rückgabetyp	Beschreibung
.derived_from_presentment(customer_cents:X)	Money	Rechnet einen Betrag (in Cent) von der lokalen Währung (Darstellungswährung) des Kunden 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, um einen Preis darzustellen.
.zero	Money	Erstellt ein neues Objekt mit einem Preis von Null.
	Money	Fügt zwei `Money`-Objekte hinzu.
–	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 USD darstellt.

Money.new(cents: 100) * 50

Erstellt ein Money-Objekt, das 1 USD darstellt, multipliziert diesen Betrag dann mit 50. Gibt ein Money-Objekt aus, das 50 USD darstellt.

Variante

Skript-Methoden, die das Variant-Objekt verwenden
Art	Rückgabetyp	Beschreibung
.id	Ganze Zahl	Gibt die ID-Nummer der Variante aus.
.price	Money	Gibt den Grundpreis der Variante aus.
.product	Produkt	Gibt das verknüpfte Produkt der Variante aus.
.skus	Liste<String>	Gibt die Artikelnummern (SKUs) der Variante zurück, die häufig zum Verfolgen des Bestands verwendet werden.
.title	String	Gibt den Titel der Variante aus.

Produkt

Skript-Methoden, die das Product-Objekt verwenden
Art	Rückgabetyp	Beschreibung
.id	Ganze Zahl	Gibt die ID-Nummer des Produkts aus.
.gift_card?	Boolescher Wert	Gibt aus, ob es sich bei dem Produkt um einen Gutschein handelt.
.tags	Liste<Tag>	Gibt eine Liste mit Strings aus, die die festgelegten Tags für dieses Produkt darstellen.
.product_type	String	Eine Kategorisierung, die häufig zum Filtern und Suchen verwendet wird und mit der ein Produkt gekennzeichnet werden kann.
.vendor	String	Gibt den Anbieter dieses Produktes aus.

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 genauso wie globale Funktionen in anderen Sprachen.

Skript-Methoden, die das Kernel-Objekt verwenden
Art	Rückgabetyp	Beschreibung
.exit	Keine	Beendet die Ausführung des aktuellen Skripts ohne Fehler. Wenn dies ausgeführt wird, bevor etwas `Output.cart` zugewiesen wurde, hat das Skript keine Auswirkungen. Dies ist eine nützliche Methode zum Beenden von Skripts, z. B. wenn der Kunde das Skript nicht ausführen kann.

Kernel-Beispiel

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

Einzelartikelmethoden

Die folgenden Methoden können bei Einzelartikel-Skripten angewandt werden:

Warenkorb

Skript-Methoden, die das Cart-Objekt in Line Item-Skripten verwenden
Art	Rückgabetyp	Beschreibung
.subtotal_price_was	Money	Gibt die Zwischensumme des Warenkorbs vor Anwendung jeglicher Rabatte aus.
.subtotal_price_changed?	Boolescher Wert	Gibt aus, ob die Zwischensumme sich geändert hat.

Einzelartikel

Skript-Methoden, die das LineItem-Objekt in Line Item-Skripten verwenden
Art	Rückgabetyp	Beschreibung
.change_line_price(Money new_price, { message: String })	Money	Ändert den Preis des Einzelartikels zum angegebenen Betrag. Eine `Nachricht` ist erforderlich. `new_price` muss niedriger als der aktuelle Preis sein.
.original_line_price	Money	Gibt den ursprünglichen Preis des Einzelartikels zurück, bevor Skripte und Rabatte angewendet wurden.
.line_price_was	Money	Gibt den Preis des Einzelartikels, bevor Änderungen vom aktuellen Skript übernommen wurden, aus.
.line_price_changed?	Boolescher Wert	Gibt zurück, ob die Eigenschaften des Einzelartikels sich geändert haben.
.change_properties(hash new_properties, { message: String })	hash	Legt neue Eigenschaften für einen Einzelartikel fest. Der ursprüngliche Eigenschaften-Hash wird in `properties_was` gespeichert und der Eigenschaften-Hash, der an die Methode übergeben wird, wird zu den neuen Eigenschaften des Einzelartikels.
.properties_was	hash	Gibt den Hash mit den ursprünglichen Eigenschaften des Einzelartikels aus, bevor irgendwelche Änderungen angewandt wurden.
.properties_changed?	Boolescher Wert	Gibt aus, ob die Eigenschaften des Einzelartikels sich geändert haben.
.split({ take: Integer })	Einzelartikel	Teilt einen Einzelartikel in zwei Einzelartikel. `take` gibt an, welche Menge aus dem ursprünglichen Einzelartikel entfernt werden soll, um den neuen Einzelartikel zu erstellen.

.split-Beispiel

Mit diesem Beispielskript wird ein Einzelartikel mit dem Namen original_line_item in zwei Einzelartikel geteilt. Der neue Einzelartikel hat die Menge 1 (angegeben durch take: 1). Das Skript wendet dann auf den neuen Einzelartikel einen reduzierten Preis mit der Meldung "Dritter Hut zum Preis von 5 Dollar" 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

Skript-Methoden, die das Variant-Objekt in Line Item-Skripten verwenden
Art	Rückgabetyp	Beschreibung
.compare_at_price	Money	Gibt den durchgestrichenen Vergleichspreis der Variante aus. Gibt `nil` aus, wenn die Variante keinen durchgestrichenen Vergleichspreis hat.

Versandarten

Die folgenden Methoden können bei Versand-Skripten angewandt werden:

Eingabe

Skript-Methoden, die das Input-Objekt in Shipping-Skripten verwenden
Art	Rückgabetyp	Beschreibung
.shipping_rates	Liste der Versandpreise	Gibt eine Liste mit allen Versandpreisen aus

Liste der Versandpreise

Skript-Methoden, die das ShippingRateList-Objekt in Shipping-Skripten verwenden
Art	Rückgabetyp	Beschreibung
.delete_if	Liste der Versandpreise	Versandkosten mithilfe eines optionalen Codeblocks löschen. Siehe die Dokumentation für die `delete_if`-Methode in Ruby.
.sort!	Liste der Versandpreise	Ordnet die Versandkosten mithilfe des Vergleichsoperators oder eines optionalen Codeblocks. Siehe die Dokumentation für die `sort!`-Methode in Ruby.
.sort_by!	Liste der Versandpreise	Sortiere die Versandkosten mit einem optionalen Codeblock. Siehe die Dokumentation für die `sort_by!`-Methode in Ruby.

Versandpreis

Skript-Methoden, die das ShippingRate-Objekt in Shipping-Skripten verwenden
Art	Rückgabetyp	Beschreibung
.code	String	Gibt den Code für die Versandkosten zurück.
.markup	Money	Gibt ggf. den Preisaufschlag für einen Versandtarif aus.
.name	String	Gibt den Namen der Versandtarifs aus. Mit der Methode `change_name` kann der Name geändert werden.
.price	Money	Gibt den Preis der Versandkosten aus.
.source	String	Gibt die dem Versandtarif zugeordnete Quelle (den Versanddienstleister) aus, sofern relevant. Die Quelle 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 auf den angegebenen festen Betrag an. Der Preis kann nicht unter 0 reduziert werden. Es ist eine Nachricht erforderlich.
.phone_required?	Boolescher Wert	Gibt `true` aus, wenn eine Telefonnummer erforderlich ist, um die Versandrate zu erhalten, oder `false`, wenn eine Telefonnummer nicht erforderlich ist.

Zahlungsmethoden

Die folgenden Methoden können bei Zahlungs-Skripten angewandt werden:

Eingabe

Skript-Methoden, die das Input-Objekt in Payment-Skripten verwenden
Art	Rückgabetyp	Beschreibung
.payment_gateways	PaymentGatewaysList	Gibt eine Liste aller im Shop verfügbaren Zahlungs-Gateways zurück.

ZahlungsportalListe

Skript-Methoden, die das PaymentGatewayList-Objekt in Payment-Skripten verwenden
Art	Rückgabetyp	Beschreibung
.delete_if	ZahlungsportalListe	Löscht Zahlungs-Gateways mithilfe eines optionalen Codeblocks. Siehe die Dokumentation für die `delete_if`-Methode in Ruby.
.sort!	ZahlungsportalListe	Sortiert Zahlungs-Gateways mithilfe des Vergleichsoperators oder eines optionalen Codeblocks. Siehe die Dokumentation für die `sort!`-Methode in Ruby.
.sort_by!	ZahlungsportalListe	Sortiert Zahlungs-Gateways mithilfe eines optionalen Codeblocks. Siehe die Dokumentation für die `sort_by!`-Methode in Ruby.

PaymentGateway

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

Beispiele

Wenn im folgenden Beispiel für ein Einzelartikel-Skript ein Kunde ein Produkt bestellt, das kein Geschenkgutschein ist, wird der Preis des Produkts um 9 USD reduziert. Außerdem wird der Gesamtbetrag angezeigt, den der Kunde während aller Besuche 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 erfahren

Erfahre mehr zu diesen Themen: