Dokumentacja API Shopify Scripts

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

Istnieją różne typy skryptów. Typ skryptu jest przypisywany podczas jego tworzenia w aplikacji Script Editor na podstawie szablonu skryptu wybranego na początku:

Skrypty pozycji pojedynczych

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

Skrypty pozycji pojedynczych, które obejmują rabatem subskrypcję, mają zastosowanie tylko do pierwszej płatności za subskrypcję. Kolejne płatności nie są objęte rabatem w ramach skryptu.

Niektóre metody mogą być używane tylko w skryptach pozycji pojedynczych.

Skrypty wysyłki

Skrypty wysyłki wchodzą w interakcję z wysyłką, mogą zmieniać metody wysyłki i przyznawać rabaty na stawki wysyłki. Skrypty te są uruchamiane, gdy w procesie realizacji zakupu pojawi się strona z opcjami wysyłki.

Skrypty wysyłki, które obejmują rabatem stawkę za wysyłkę subskrypcji, mają zastosowanie tylko do pierwszej płatności za subskrypcję. Kolejne płatności nie są objęte rabatem w ramach skryptu.

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

Skrypty płatności

Skrypty płatności wchodzą w interakcję z płatnościami i mogą zmieniać nazwy, ukrywać i zmieniać kolejność bramek płatniczych. Pamiętaj, że skrypty płatności nie wchodzą w interakcję z bramkami płatniczymi wyświetlanymi przed ekranem realizacji zakupu, takimi jak Apple Pay. Skrypty te są uruchamiane, gdy w procesie realizacji zakupu pojawi się strona płatności.

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

Na tej stronie

Metody ogólne

Poniższych metod można używać w dowolnym typie skryptu:

Dane wejściowe

Metody wejściowe skryptu
Metoda	Typ zwracany	Opis
.cart	Cart	Zwraca modyfikowalny obiekt koszyka.
.locale	ciąg znaków	Zwraca ustawienia regionalne klienta. Na przykład: `en`, `fr` lub `pt-BR`.

Cart

Obiekt koszyka jest dostępny tylko w sklepie online. Niektóre przerwane realizacje zakupu mają dostęp do obiektu koszyka. Jeśli jednak realizacja zakupu została zamknięta, a następnie klient odwiedza stronę przerwanej realizacji zakupu, jest on kierowany do wstępnie wypełnionej strony realizacji zakupu i obiekt koszyka już nie istnieje. Dzieje się tak, ponieważ witryna sklepu została pominięta przez e-mail dotyczący przerwanej realizacji zakupu.

Metoda Typ zwracany Opis

.customer Customer 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

Metody skryptu używające obiektu Cart
Metoda	Typ zwracany	Opis
.customer	Customer	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	Zwraca: `nil`, jeśli koszyk nie ma kodu rabatowego `CartDiscount::FixedAmount`, jeśli koszyk ma stałą kwotę rabatu `CartDiscount::Percentage`, jeśli koszyk ma rabat procentowy `CartDiscount::Shipping`, jeśli koszyk ma rabat na wysyłkę Zwraca pojedynczy kod rabatowy (patrz: Ograniczenia) `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 USD, a skrypt zmniejsza cenę koszyka poniżej 50 USD, `discount_code` jest nadal obecny, ale cena koszyka się nie zmienia. <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><LineItem></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><String></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>

Zwraca:

nil, jeśli koszyk nie ma kodu rabatowego
CartDiscount::FixedAmount, jeśli koszyk ma stałą kwotę rabatu
CartDiscount::Percentage, jeśli koszyk ma rabat procentowy
CartDiscount::Shipping, jeśli koszyk ma rabat na wysyłkę
Zwraca pojedynczy kod rabatowy (patrz: Ograniczenia)

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 USD, a skrypt zmniejsza cenę koszyka poniżej 50 USD, discount_code jest nadal obecny, ale cena koszyka się nie zmienia.

<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

Metody skryptu używające obiektu CartDiscount::FixedAmount
Metoda	Typ zwracany	Opis
.code	Ciąg znaków	Zwraca kod rabatowy użyty do zastosowania rabatu.
.amount	Money	Zwraca kwotę pieniężną rabatu.
.reject({ message: String })	nil	Odrzuca kod rabatowy zastosowany do koszyka. Wymagany jest `komunikat`.
.rejected?	Boolean	Zwraca informację, czy kod rabatowy został odrzucony.

CartDiscount::Percentage

Metody skryptu używające obiektu CartDiscount::Percentage
Metoda	Typ zwracany	Opis
.code	Ciąg znaków	Zwraca kod rabatowy użyty do zastosowania rabatu.
.percentage	Liczba dziesiętna	Zwraca wartość procentową rabatu.
.reject({ message: String })	nil	Odrzuca kod rabatowy zastosowany do koszyka. Wymagany jest `komunikat`.
.rejected?	Boolean	Zwraca informację, czy kod rabatowy został odrzucony.

CartDiscount::Shipping

Metody skryptu używające obiektu CartDiscount::Shipping
Metoda	Typ zwracany	Opis
.code	Ciąg znaków	Zwraca kod rabatowy użyty do zastosowania rabatu.
.reject({ message: String })	nil	Odrzuca kod rabatowy zastosowany do koszyka. Wymagany jest `komunikat`.
.rejected?	Boolean	Zwraca informację, czy kod rabatowy został odrzucony.

Klient

Metody skryptu używające obiektu Klient
Metoda	Typ zwracany	Opis
.id	Liczba całkowita	Zwraca numer ID klienta.
.email	Ciąg znaków	Zwraca adres e-mail klienta.
.tags	Lista<Tag>	Zwraca listę ciągów znaków reprezentujących tagi ustawione dla klienta.
.orders_count	Liczba całkowita	Zwraca łączną liczbę zamówień złożonych przez klienta.
.total_spent	Money	Zwraca łączną kwotę wydaną przez klienta na wszystkie zamówienia.
.accepts_marketing?	Boolean	Zwraca informację, czy klient akceptuje działania marketingowe.

LineItem

Metody skryptu używające obiektu LineItem
Metoda	Typ zwracany	Opis
.grams	gramy	Zwraca łączną wagę pozycji pojedynczej.
.line_price	Money	Cena pozycji pojedynczej.
.discounted?	Boolean	Zwraca informację, czy cena pozycji pojedynczej została obniżona za pomocą skryptu lub ręcznie zastosowanego rabatu. Użycie kodów rabatowych nie ma wpływu 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 ID planu sprzedaży dla pozycji pojedynczej. Ta metoda jest przydatna, gdy sklep sprzedaje subskrypcje i chcesz, aby skrypt wykrywał, kiedy wariant produktu jest sprzedawany w ramach subskrypcji.

Lista

Metody skryptu używające obiektu Lista
Metoda	Typ zwracany	Opis
.new	Lista	Tworzy nowy obiekt reprezentujący listę.
.[]	Element lub nil	Zwraca element o podanym indeksie.
.&	Lista	Zwraca nową listę zawierającą elementy wspólne dla obu list, bez duplikatów.
.delete_if	Lista	Usuwa elementy za pomocą opcjonalnego bloku kodu. Zobacz dokumentację metody `delete_if` w języku Ruby.
.empty?	Boolean	Zwraca wartość `true`, jeśli lista nie zawiera żadnych elementów.
.first	Element lub nil	Zwraca pierwszy element lub `nil`, jeśli lista jest pusta.
.index(*args, &block)	liczba całkowita lub nil	Zwraca indeks pierwszego elementu listy. Jeśli zamiast argumentu podany jest blok, zwraca indeks pierwszego elementu, dla którego blok jest prawdziwy.
.rindex(*args, &block)	liczba całkowita lub nil	Zwraca indeks ostatniego elementu listy. Jeśli zamiast argumentu podany jest blok, zwraca indeks pierwszego elementu, dla którego blok jest prawdziwy.
.last	Element lub nil	Zwraca ostatni element lub `nil`, jeśli lista jest pusta.
.length	liczba całkowita	Zwraca liczbę elementów na liście.
.size	liczba całkowita	Alias dla length.
.each(*args, &block)	Lista	Wywołuje blok jeden raz dla każdego elementu na liście, przekazując element jako parametr do bloku.

ShippingAddress

Metody skryptu używające obiektu ShippingAddress
Metoda	Typ zwracany	Opis
.name	ciąg znaków	Zwraca imię i nazwisko osoby powiązanej z adresem wysyłki.
.address1	ciąg znaków	Zwraca część adresu wysyłki obejmującą ulicę.
.address2	ciąg znaków	Zwraca opcjonalne dodatkowe pole części adresu wysyłki obejmującej ulicę.
.phone	ciąg znaków	Zwraca numer telefonu adresu wysyłki.
.city	ciąg znaków	Zwraca miasto adresu wysyłki.
.zip	ciąg znaków	Zwraca kod pocztowy adresu wysyłki.
.province	ciąg znaków	Zwraca prowincję/stan adresu wysyłki.
.province_code	ciąg znaków	Zwraca skróconą wartość prowincji/stanu adresu wysyłki.
.country_code	ciąg znaków	Zwraca skróconą wartość kraju adresu wysyłki.

Money

Metody skryptu używające obiektu Money
Metoda	Typ zwracany	Opis
.derived_from_presentment(customer_cents:X)	Money	Konwertuje kwotę (w centach) z lokalnej waluty klienta (waluty prezentacji) na walutę sklepu. Ta metoda akceptuje parametr `customer_cents`, który przyjmuje liczbę w centach. Na przykład: `Money.derived_from_presentment(customer_cents: 500)`.
.new	Money	Tworzy nowy obiekt reprezentujący cenę.
.zero	Money	Tworzy nowy obiekt z ceną równą zero.
+	Money	Dodaje dwa obiekty `Money`.
-	Money	Odejmuje jeden obiekt `Money` od drugiego.
*	Money	Mnoży obiekt `Money` przez liczbę.

Przykłady dla Money

Money.new(cents: 1000)

Tworzy obiekt Money reprezentujący 1000 centów, czyli 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.

Wariant

Metody skryptowe dla obiektu Variant
Metoda	Typ zwracany	Opis
.id	Liczba całkowita	Zwraca numer ID wariantu.
.price	Money	Zwraca cenę jednostkową wariantu.
.product	Product	Zwraca powiązany produkt wariantu.
.skus	List<String>	Zwraca jednostki magazynowe (SKU) wariantu, które są często używane do śledzenia zapasów.
Skrypty Shopify	Ciąg znaków	Zwraca tytuł wariantu.

Produkt

Metody skryptowe dla obiektu Product
Metoda	Typ zwracany	Opis
.id	Liczba całkowita	Zwraca numer ID produktu.
.gift_card?	Boolean	Zwraca informację, czy produkt jest kartą prezentową.
.tags	Lista<Tag>	Zwraca listę ciągów znaków reprezentujących tagi ustawione dla tego produktu.
.product_type	Ciąg znaków	Kategoryzacja, którą można przypisać do produktu, powszechnie używana do filtrowania i wyszukiwania.
.vendor	Ciąg znaków	Zwraca dostawcę tego produktu.

Kernel

Kernel to moduł języka Ruby dołączany do każdej klasy. Dzięki temu jego metody są dostępne dla każdego obiektu. Metody te działają w ten sam sposób co funkcje globalne w innych językach.

Metody skryptowe dla obiektu Kernel
Metoda	Typ zwracany	Opis
.exit	brak	Kończy wykonanie bieżącego skryptu bez błędu. Jeśli zostanie to uruchomione, zanim cokolwiek zostanie przypisane do `Output.cart`, skrypt nie przyniesie żadnego efektu. Jest to przydatny sposób na zakończenie skryptów, na przykład, jeśli klient nie jest uprawniony do uruchomienia skryptu.

Przykład dla 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ą dostępne tylko w skryptach pozycji pojedynczych:

Cart

Metody skryptowe dla obiektu Cart w skryptach pozycji pojedynczych
Metoda	Typ zwracany	Opis
.subtotal_price_was	Money	Zwraca sumę częściową koszyka przed zastosowaniem jakichkolwiek rabatów.
.subtotal_price_changed?	Boolean	Zwraca informację, czy suma częściowa uległa zmianie.

LineItem

Metody skryptowe dla obiektu LineItem w skryptach pozycji pojedynczych
Metoda	Typ zwracany	Opis
.change_line_price(Money new_price, { message: String })	Money	Zmienia cenę pozycji pojedynczej na określoną kwotę. Wymagany jest `komunikat`. `new_price` musi być niższa od bieżącej ceny.
.original_line_price	Money	Zwraca pierwotną cenę pozycji pojedynczej przed zastosowaniem skryptów i rabatów.
.line_price_was	Money	Zwraca cenę pozycji pojedynczej przed wprowadzeniem zmian przez bieżący skrypt.
.line_price_changed?	Boolean	Zwraca informację, czy cena pozycji pojedynczej uległa zmianie.
.change_properties(hash new_properties, { message: String })	hash	Ustawia nowe właściwości dla pozycji pojedynczej. Oryginalny hash właściwości jest przechowywany w `properties_was`, a hash właściwości przekazywany do metody staje się nowymi właściwościami pozycji pojedynczej.
.properties_was	hash	Zwraca oryginalny hash właściwości pozycji pojedynczej sprzed zastosowania jakichkolwiek zmian.
.properties_changed?	Boolean	Zwraca informację, czy właściwości pozycji pojedynczej zostały zmienione.
.split({ take: Integer })	LineItem	Dzieli pozycję pojedynczą na dwie pozycje pojedyncze. `take` określa, jaką ilość należy usunąć z oryginalnej pozycji pojedynczej w celu utworzenia nowej pozycji pojedynczej.

Przykład dla .split

Ten przykładowy skrypt dzieli pozycję pojedynczą o nazwie original_line_item na dwie pozycje pojedyncze. Nowa pozycja pojedyncza ma ilość równą 1 (określoną przez take: 1). Następnie skrypt stosuje obniżoną cenę do nowej pozycji pojedynczej z komunikatem „Third hat for 5 dollars”.

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 skryptowe dla obiektu Variant w skryptach pozycji pojedynczych
Metoda	Typ zwracany	Opis
.compare_at_price	Money	Zwraca cenę porównawczą wariantu. Zwraca wartość `nil`, jeśli wariant nie ma ceny porównawczej.

Metody wysyłki

Poniższe metody są dostępne w skryptach wysyłki:

Dane wejściowe

Metody skryptowe dla obiektu Input w skryptach wysyłki
Metoda	Typ zwracany	Opis
.shipping_rates	ShippingRateList	Zwraca listę wszystkich stawek wysyłki.

ShippingRateList

Metody skryptu używające obiektu ShippingRateList w skryptach wysyłki
Metoda	Typ zwracany	Opis
.delete_if	ShippingRateList	Usuwa stawki wysyłki za pomocą opcjonalnego bloku kodu. Zapoznaj się z dokumentacją dla metody `delete_if` języka Ruby.
.sort!	ShippingRateList	Sortuje stawki wysyłki za pomocą operatora porównania lub opcjonalnego bloku kodu. Zapoznaj się z dokumentacją dla metody `sort!` języka Ruby.
.sort_by!	ShippingRateList	Sortuje stawki wysyłki za pomocą opcjonalnego bloku kodu. Zapoznaj się z dokumentacją dla metody `sort_by!` języka Ruby.

ShippingRate

Metody skryptu używające obiektu ShippingRate w skryptach wysyłki
Metoda	Typ zwracany	Opis
.code	Ciąg znaków	Zwraca kod stawki wysyłki.
.markup	Money	Zwraca narzut dla stawki wysyłki, jeśli ma to zastosowanie.
.name	Ciąg znaków	Zwraca nazwę stawki wysyłki. Można ją zmodyfikować za pomocą metody `change_name`.
.price	Money	Zwraca cenę stawki wysyłki.
.source	Ciąg znaków	Zwraca źródło (przewoźnika) powiązane ze stawką wysyłki, jeśli jest to istotne. Nie można go modyfikować.
.change_name(String new_name)	Ciąg znaków	Zmienia nazwę (maksymalnie 255 znaków) stawki wysyłki. Zmiana, usunięcie lub ukrycie źródła nie jest możliwe.
.apply_discount(Money discount, { message: String })	Money	Stosuje rabat o określonej ustalonej kwocie. Cena nie może zostać obniżona poniżej 0. Wiadomość jest wymagana.
.phone_required?	Boolean	Zwraca wartość `true`, jeśli do uzyskania stawki wysyłki wymagany jest numer telefonu, lub `false`, jeśli numer telefonu nie jest wymagany.

Metody płatności

Poniższe metody mogą być używane w skryptach płatności:

Dane wejściowe

Metody skryptu używające obiektu Input w skryptach płatności
Metoda	Typ zwracany	Opis
.payment_gateways	PaymentGatewaysList	Zwraca listę wszystkich bramek płatniczych w sklepie.

PaymentGatewayList

Metody skryptu używające obiektu PaymentGatewayList w skryptach płatności
Metoda	Typ zwracany	Opis
.delete_if	PaymentGatewayList	Usuwa bramki płatnicze za pomocą opcjonalnego bloku kodu. Zapoznaj się z dokumentacją dla metody `delete_if` języka Ruby.
.sort!	PaymentGatewayList	Sortuje bramki płatnicze za pomocą operatora porównania lub opcjonalnego bloku kodu. Zapoznaj się z dokumentacją dla metody `sort!` języka Ruby.
.sort_by!	PaymentGatewayList	Sortuje bramki płatnicze za pomocą opcjonalnego bloku kodu. Zapoznaj się z dokumentacją dla metody `sort_by!` języka Ruby.

PaymentGateway

Metoda	Typ zwracany	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 przez sklep. 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 zmieniać nazw bramek płatniczych z logo.

Przykłady

W poniższym przykładzie skryptu dla pozycji pojedynczej, gdy klient zamawia produkt, który nie jest kartą prezentową, cena produktu jest obniżana o 9 USD. Ponadto wyświetlana jest łączna kwota, którą klient wydał 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 na temat: