Informacje dotyczące interfejsu API Shopify Scripts

Ta strona została wydrukowana dnia Apr 25, 2024. Aby zapoznać się z aktualną wersją, odwiedź https://help.shopify.com/pl/manual/checkout-settings/script-editor/shopify-scripts.

Skrypty są pisane przy użyciu interfejsu API Ruby, który zapewnia dużą kontrolę i elastyczność.

Istnieją różne typy skryptów. Typ przypisuje się do skryptu podczas tworzenia skryptu w aplikacji Script Editor na podstawie wybranego szablonu skryptu:

Skrypty pozycji pojedynczych

Skrypty pozycji pojedynczych wpływają na pozycje w koszyku i mogą zmieniać ceny oraz przyznawać rabaty. Skrypty te są uruchamiane po dokonaniu zmiany w koszyku.

Skrypty pozycji pojedynczych obniżające opłatę subskrypcyjną mają zastosowanie tylko do pierwszej płatności za subskrypcję. Kolejne płatności za subskrypcję nie są obniżane przez skrypt.

Niektóre metody mogą być stosowane tylko w skryptach pozycji liniowych.

Skrypty wysyłki

Skrypty wysyłki współdziałają z wysyłką i mogą zmieniać metody wysyłki oraz przyznawać rabaty na stawki wysyłki. Skrypty te są uruchamiane po przejściu na stronę opcji wysyłki podczas realizacji zakupu.

Skrypty pozycji obniżające stawkę wysyłki subskrypcji mają zastosowanie tylko do pierwszej płatności za subskrypcję. Kolejne płatności nie są obniżane przez skrypt.

Niektóre metody mogą być stosowane tylko w skryptach wysyłki.

Skrypty płatności

Skrypty płatności współdziałają z płatnościami i mogą zmieniać nazwy, ukrywać i zmieniać kolejność bramek płatniczych Należy pamiętać, że skrypty płatności nie działają z bramkami płatniczymi wyświetlanymi przed ekranem realizacji zakupu, takimi jak Apple Pay. Takie skrypty są uruchamiane po przejściu na stronę płatności podczas realizacji zakupu.

Niektóre metody mogą być stosowane tylko w skryptach płatności.

Na tej stronie

Metody ogólne

Poniższe metody można stosować w każdym typie skryptu:

Dane wejściowe

Metody skryptu wykorzystujące dane wejściowe
Metoda Typ zwrotu Opis
.cart Koszyk Zwraca modyfikowalny obiekt Koszyk.
.locale ciąg znaków Zwraca ustawienia regionalne klienta. Na przykład en, fr lub pt-BR.

Koszyk

Obiekt Koszyk jest dostępny tylko w sklepie online. Dostęp do obiektu Koszyk jest możliwy w przypadku niektórych przerwanych realizacji zakupu. Jeśli jednak strona realizacji zakupu została zamknięta, klient próbujący wyświetlić stronę przerwanej realizacji zakupu zostaje przekierowany na wstępnie wypełnioną stronę realizacji zakupu, a obiekt Koszyk już nie istnieje. Jest to spowodowane pominięciem witryny sklepu przez e-mail dotyczący przerwanej realizacji zakupu.

Metody skryptu wykorzystujące obiekt Koszyk
Metoda Typ zwrotu Opis
.customer Klient Zwraca właściciela koszyka (jeśli istnieje).
.shipping_address ShippingAddress Zwraca adres wysyłki właściciela koszyka (jeśli istnieje).
.discount_code różny Zwroty:

discount_code jest obecny, jeśli do koszyka zastosowano rabat. Nie musi to oznaczać zmiany ceny koszyka. Na przykład, jeśli rabat dotyczy koszyków o wartości powyżej 50 zł, a skrypt obniża cenę koszyka poniżej 50 zł, discount_code istnieje nadal, ale cena koszyka się nie zmienia.

Zobacz przykład discount_code.
.line_items List<LineItem> Zwraca listę zawierającą pozycje pojedyncze w koszyku.
.presentment_currency List<String> Zwraca walutę lokalną (wyświetlaną) klienta (w formacie ISO 4217). Na przykład USD.
.subtotal_price Pieniądze Zwraca sumę częściową ceny koszyka po zastosowaniu rabatów dla pozycji pojedynczych, ale przed zastosowaniem kodów rabatowych.
.total_weight gramy Zwraca całkowitą wagę wszystkich pozycji pojedynczych w koszyku.

CartDiscount::FixedAmount

Metody skryptu wykorzystujące obiekt CartDiscount::FixedAmount
Metoda Typ zwrotu Opis
.code Ciąg znaków Zwraca kod rabatowy użyty do zastosowania rabatu.
.amount Pieniądze Zwraca kwotę rabatu.
.reject({ message: String }) Zero Odrzuca kod rabatowy zastosowany do koszyka. Wymagana jest wiadomość message.
.rejected? Wartość logiczna Wskazuje, czy kod rabatowy został odrzucony.

CartDiscount::Percentage

Metody skryptu wykorzystujące obiekt CartDiscount::Percentage
Metoda Typ zwrotu Opis
.code Ciąg znaków Zwraca kod rabatowy użyty do zastosowania rabatu.
.percentage Ułamek dziesiętny Zwraca kwotę procentową rabatu.
.reject({ message: String }) Zero Odrzuca kod rabatowy zastosowany do koszyka. Wymagana jest wiadomość message.
.rejected? Wartość logiczna Wskazuje, czy kod rabatowy został odrzucony.

CartDiscount::Shipping

Metody skryptu wykorzystujące obiekt CartDiscount::Shipping
Metoda Typ zwrotu Opis
.code Ciąg znaków Zwraca kod rabatowy użyty do zastosowania rabatu.
.reject({ message: String }) Zero Odrzuca kod rabatowy zastosowany do koszyka. Wymagana jest wiadomość message.
.rejected? Wartość logiczna Wskazuje, czy kod rabatowy został odrzucony.

Klient

Metody skryptu wykorzystujące obiekt Klient
Metoda Typ zwrotu Opis
.id Liczba całkowita Zwraca numer identyfikacyjny klienta.
.email Ciąg znaków Zwraca adres e-mail klienta.
.tags List<Tag> Zwraca listę ciągów znaków reprezentujących wszystkie tagi ustawione dla klienta.
.orders_count Liczba całkowita Zwraca całkowitą liczbę zamówień złożonych przez klienta.
.total_spent Pieniądze Zwraca całkowitą kwotę wydaną przez klienta na wszystkie zamówienia.
.accepts_marketing? Wartość logiczna Określa, czy klient wyraża zgodę na marketing.

LineItem

<tdgramy
Metody skryptu wykorzystujące obiekt LineItem
Metoda Typ zwrotu Opis
.grams Zwraca całkowitą wagę pozycji pojedynczej.
.line_price Pieniądze Cena pozycji pojedynczej
.discounted? Wartość logiczna Zwraca informację, czy cena pozycji została obniżona przez skrypt czy ręcznie zastosowany rabat. Użycie kodów rabatowych nie wpływa na zwracaną wartość.
.properties hash Zwraca właściwości, które zostały określone dla tej pozycji pojedynczej
.variant Wariant Zwraca określony wariant produktu reprezentowany przez pozycję pojedynczą.
.quantity Liczba całkowita Zwraca ilość tej pozycji pojedynczej.
.selling_plan_id Liczba całkowita Zwraca identyfikator planu sprzedaży dla pozycji. Ta metoda jest przydatna, gdy sklep sprzedaje subskrypcje i chcesz, aby skrypt wykrył, kiedy wariant produktu jest sprzedawany w ramach subskrypcji.

Lista

Metody skryptu wykorzystujące obiekt Lista
Metoda Typ zwrotu Opis
.new Lista Tworzy nowy obiekt do reprezentowania listy.
.[] Element lub brak

Zwraca element pod określonym indeksem.
.& Lista

Zwraca nową listę zawierającą elementy wspólne dla dwóch list, bez duplikatów.
.delete_if Lista Usuwanie elementów za pomocą opcjonalnego bloku kodu. Zapoznaj się z dokumentacją metody języka Ruby delete_if.
.empty? Wartość logiczna

Zwraca wartość true, jeśli lista nie zawiera żadnych elementów.
.first Element lub brak

Zwraca pierwszy element lub nil, jeśli lista jest pusta.
.index(*args, &block) int lub nil

Zwraca indeks pierwszego elementu listy. Jeśli zamiast argumentu zostanie podany blok, zwraca indeks pierwszego elementu, dla którego blok ma wartość PRAWDA.
.rindex(*args, &block) int lub nil

Zwraca indeks ostatniego elementu listy. Jeśli zamiast argumentu zostanie podany blok, zwraca indeks pierwszego elementu, dla którego blok ma wartość PRAWDA.
.last Element lub brak

Zwraca ostatni element lub nil, jeśli lista jest pusta.
.length int

Zwraca liczbę elementów na liście.
.size int

Alias dla długości.
.each(*args, &block) Lista

Wywołuje blok jednorazowo dla każdego elementu na liście, przekazując element jako parametr do bloku.

ShippingAddress

Metody skryptu wykorzystujące obiekt ShippingAddress
Metoda Typ zwrotu Opis
.name ciąg znaków Zwraca nazwisko osoby powiązanej z adresem wysyłki.
.address1 ciąg znaków Zwraca część adresu ulicy z adresu wysyłki.
.address2 ciąg znaków Zwraca opcjonalne dodatkowe pole części adresu ulicy z adresu wysyłki.
.phone ciąg znaków Zwraca numer telefonu z adresu wysyłki.
.city ciąg znaków Zwraca miasto z adresu wysyłki.
.zip ciąg znaków Zwraca kod pocztowy z adresu wysyłki.
.province ciąg znaków Zwraca województwo/prowincję/stan z adresu wysyłki.
.province_code ciąg znaków Zwraca skróconą wartość województwa/prowincji/stanu z adresu wysyłki.
.country_code ciąg znaków Zwraca skróconą wartość kraju z adresu wysyłki.

Pieniądze

Metody skryptu wykorzystujące obiekt Pieniądze
Metoda Typ zwrotu Opis
.derived_from_presentment(customer_cents:X) Pieniądze Konwertuje kwotę (w centach) z lokalnej (wyświetlanej) waluty klienta na walutę sklepu. W tej metodzie przyjmowany jest parametr customer_cents, który przyjmuje liczbę w centach. Na przykład Money.derived_from_presentment(customer_cents: 500).
.new Pieniądze Tworzy nowy obiekt reprezentujący cenę.
.zero Pieniądze

Tworzy nowy obiekt z ceną wynoszącą zero.
+ Pieniądze Dodaje dwa obiekty Pieniądze.
- Pieniądze Odejmuje jeden obiekt Pieniądze od innego.
* Pieniądze Mnoży obiekt Pieniądze przez liczbę.

Przykłady obiektów Money

Money.new(cents: 1000)

Tworzy obiekt Money reprezentujący 1000 centów lub 10 USD.

Money.new(cents: 100) * 50

Tworzy obiekt Money reprezentujący 1 USD, a następnie mnoży tę kwotę przez 50. Zwraca obiekt Money reprezentujący 50 USD.

Variant

Metody skryptu wykorzystujące obiekt Wariant
Metoda Typ zwrotu Opis
.id Liczba całkowita Zwraca numer identyfikacyjny wariantu.
.price Pieniądze Zwraca cenę jednostkową wariantu.
.product Produkt Zwraca powiązany produkt wariantu.
.skus List<String> Zwraca jednostki magazynowania (SKU) wariantu, które są często używane do śledzenia zapasów.
.title Ciąg znaków Zwraca tytuł wariantu.

Produkt

Metody skryptu wykorzystujące obiekt Produkt
Metoda Typ zwrotu Opis
.id Liczba całkowita Zwraca numer identyfikacyjny produktu.
.gift_card? Wartość logiczna Wskazuje, czy produkt jest kartą prezentową.
.tags List<Tag> Zwraca listę ciągów znaków reprezentujących tagi ustawione dla tego produktu.
.product_type Ciąg znaków Kategoryzacja, za pomocą której produkt można oznaczyć produkt, używana często do filtrowania i wyszukiwania.
.vendor Ciąg znaków Zwraca dostawcę tego produktu.

Kernel

Kernel to moduł Ruby, który jest zawarty w każdej klasie. W rezultacie jego metody są dostępne dla każdego obiektu. Metody te działają w taki sam sposób, jak funkcje globalne w innych językach.

Metody skryptu wykorzystujące obiekt Kernel
Metoda Typ zwrotu Opis
.exit none Kończy wykonywanie bieżącego skryptu bez błędów. W przypadku uruchomienia zanim cokolwiek zostanie przypisane do Output.cart, skrypt nie przyniesie żadnego efektu. Jest to przydatna metoda wyjścia ze skryptów, jeśli klient nie jest uprawniony do uruchomienia skryptu.

Przykład obiektu Kernel

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

Metody pozycji pojedynczych

Poniższe metody są używane tylko w skryptach pozycji pojedynczych:

Koszyk

Metody skryptu wykorzystujące obiekt Koszyk w skryptach pozycji pojedynczych
Metoda Typ zwrotu Opis
.subtotal_price_was Pieniądze Zwraca sumę częściową koszyka przed zastosowaniem rabatów.
.subtotal_price_changed? Wartość logiczna Określa, czy zmieniła się cena cząstkowa.

LineItem

Metody skryptu wykorzystujące obiekt LineItem w skryptach pozycji pojedynczych
Metoda Typ zwrotu Opis
.change_line_price(Pieniądze new_price, { message: String }) Pieniądze Zmienia cenę pozycji pojedynczej na określoną kwotę. Wymagana jest wiadomość message. Nowa cena new_price musi być niższa od bieżącej.
.original_line_price Pieniądze Zwraca oryginalną cenę pozycji pojedynczej przed zastosowaniem skryptów i rabatów.
.line_price_was Pieniądze Zwraca cenę pozycji pojedynczej przed zastosowaniem zmian przez bieżący skrypt.
.line_price_changed? Wartość logiczna Określa, czy cena pozycji pojedynczej uległa zmianie.
.change_properties(hash new_properties, { message: String }) hash Ustawia nowe właściwości pozycji pojedynczej. Skrót właściwości oryginalnych jest przechowywany w properties_was, a skrót właściwości przekazany do metody staje się nowymi właściwościami pozycji pojedynczej.
.properties_was hash Zwraca skrót oryginalnych właściwości pozycji pojedynczej przed zastosowaniem zmian.
.properties_changed? Wartość logiczna Określa, czy właściwości pozycji pojedynczej uległy zmianie.
.split({ take: Integer }) LineItem Dzieli pozycję pojedynczą na dwie pozycje. take określa, jaką ilość należy usunąć z oryginalnej pozycji pojedynczej, aby utworzyć nową pozycję.

Przykładowy .split

Ten przykładowy skrypt dzieli pozycję pojedynczą o nazwie original_line_item na dwie pozycje. Nowa pozycja pojedyncza ma ilość 1 (określoną przez take: 1). Następnie skrypt stosuje obniżoną cenę do nowej pozycji pojedynczej z wiadomością: „Trzeci kapelusz za 5 dolarów”.

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

Wariant

Metody skryptu wykorzystujące obiekt Wariant w skryptach pozycji pojedynczych
Metoda Typ zwrotu Opis
.compare_at_price Pieniądze Zwraca cenę do porównania wariantu. Zwraca nil, jeśli wariant nie ma ceny do porównania.

Metody wysyłki

Poniższe metody są używane w skryptach wysyłki:

Dane wejściowe

Metody skryptu wykorzystujące obiekt Dane wejściowe w skryptach wysyłki
Metoda Typ zwrotu Opis
.shipping_rates ShippingRateList Zwraca listę wszystkich stawek wysyłki.

ShippingRateList

Metody skryptu wykorzystujące obiekt ShippingRateList w skryptach wysyłki
Metoda Typ zwrotu Opis
.delete_if ShippingRateList Usuwanie stawek wysyłki za pomocą opcjonalnego bloku kodu. Zapoznaj się z dokumentacją metody języka Ruby delete_if.
.sort! ShippingRateList Sortowanie stawek wysyłki za pomocą operatora porównania lub opcjonalnego bloku kodu. Zapoznaj się z dokumentacją metody języka Ruby sort!.
.sort_by! ShippingRateList Sortowanie stawek wysyłki za pomocą opcjonalnego bloku kodu. Zapoznaj się z dokumentacją metody języka Ruby sort_by!.

ShippingRate

Metody skryptu wykorzystujące obiekt ShippingRate w skryptach wysyłki
Metoda Typ zwrotu Opis
.code Ciąg znaków Zwraca kod stawki wysyłki.
.markup Pieniądze Zwraca znacznik stawki wysyłki, jeśli taki występuje.
.name Ciąg znaków Zwraca nazwę stawki wysyłki. Można ją zmienić za pomocą metody change_name.
.price Pieniądze Zwraca cenę stawki wysyłki.
.source Ciąg znaków Zwraca źródło (przewoźnika) powiązane ze stawką wysyłki (w odpowiednich przypadkach). Nie można go modyfikować.
.change_name(String new_name) Ciąg znaków Zmienia nazwę (maksymalnie 255 znaków) stawki wysyłki. Źródła nie można zmienić, usunąć ani ukryć.
.apply_discount(Pieniądze discount, { message: String }) Pieniądze Stosuje rabat w określonej stałej kwocie. Cena nie może zostać obniżona poniżej 0. Wymagana jest wiadomość.
.phone_required? Wartość logiczna Zwraca wartość true, jeśli numer telefonu jest wymagany do uzyskania stawki wysyłki, lub false, jeśli numer telefonu nie jest wymagany.

Metody płatności

Poniższe metody są używane w skryptach płatności:

Dane wejściowe

Metody skryptu wykorzystujące obiekt Dane wejściowe w skryptach płatności
Metoda Typ zwrotu Opis
.payment_gateways PaymentGatewaysList Zwraca listę wszystkich bramek płatniczych w sklepie.

PaymentGatewayList

Metody skryptu wykorzystujące obiekt PaymentGatewayList w skryptach płatności
Metoda Typ zwrotu Opis
.delete_if PaymentGatewayList Usuwanie bramek płatniczych pomocą opcjonalnego bloku kodu. Zapoznaj się z dokumentacją metody języka Ruby delete_if.
.sort! PaymentGatewayList Sortowanie bramek płatniczych za pomocą operatora porównania lub opcjonalnego bloku kodu. Zapoznaj się z dokumentacją metody języka Ruby sort!.
.sort_by! PaymentGatewayList Sortowanie bramek płatniczych za pomocą opcjonalnego bloku kodu. Zapoznaj się z dokumentacją metody języka Ruby sort_by!.

PaymentGateway

Metoda Typ zwrotu Opis
.name Ciąg znaków Zwraca nazwę bramki płatniczej.
.enabled_card_brands List<String>

Jeśli bramka płatnicza obsługuje karty kredytowe, zwraca listę typów kart kredytowych akceptowanych w sklepie. Jeśli bramka nie obsługuje kart kredytowych, zwraca pustą listę.
.change_name(String new_name) Ciąg znaków Zmienia nazwę bramki płatniczej. Nie można zmienić nazwy bramek płatniczych z logo.

Przykłady

W poniższym przykładzie skryptu pozycji pojedynczej, gdy klient zamawia produkt, który nie jest kartą prezentową, cena produktu jest obniżana o 9 USD. Wyświetlana jest także łączna kwota wydana przez klienta podczas wszystkich wizyt w Twoim sklepie:

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

Dowiedz się więcej

Dowiedz się więcej o:

Gotowy(-a) do rozpoczęcia sprzedaży za pomocą Shopify?

Wypróbuj za darmo