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.

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.

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 Sie, 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.

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 Warenkörbe 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 den eigentlichen Shop 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:

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.

Schauen Sie sich 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 lokale Wä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 Ganze Zahl 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.

Einzelartikel

<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 ein Rabatt den Preis des Einzelartikels geändert hat.
.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.

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.

.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 Ihres 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 Geschenkgutschein 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 Sortieren Sie 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 String Gibt den Preisaufschlag für die Beschreibung der Versandkosten aus.
.name String Gibt den Namen der Versandkosten aus.
.price Money Gibt den Preis der Versandkosten aus.
.source String Gibt die den Versandkosten zugewiesene Quelle (das Versandunternehmen) zurück.
.change_name(String new_name, { message: String }) String Ändert den Namen (maximal 255 Zeichen) des Versandpreises. Eine Nachricht ist erforderlich.
.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.

Zahlungsarten

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.

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 Ihrem 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

Erfahren Sie mehr zu diesen Themen:

Sind Sie bereit, mit Shopify zu verkaufen?

Probieren Sie es kostenlos aus