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
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.
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:
|
.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
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
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
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
Art | Rückgabetyp | Beschreibung |
---|---|---|
.id | Ganze Zahl | Gibt die ID-Nummer der Kunden aus. |
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
Art | Rückgabetyp | Beschreibung |
---|---|---|
.grams | <tdgramsGibt 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
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 |
.first | Element oder nil |
Gibt das erste Element der Liste aus. Ist die Liste leer, wird |
.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 |
.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
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
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
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
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.
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
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
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
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
Art | Rückgabetyp | Beschreibung |
---|---|---|
.shipping_rates | Liste der Versandpreise | Gibt eine Liste mit allen Versandpreisen aus |
Liste der Versandpreise
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
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
Art | Rückgabetyp | Beschreibung |
---|---|---|
.payment_gateways | PaymentGatewaysList | Gibt eine Liste aller im Shop verfügbaren Zahlungs-Gateways zurück. |
ZahlungsportalListe
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: