Shopify scriptek – API-referencia

A szkriptek egy Ruby API-val íródnak, amely nagyfokú irányítást és rugalmasságot biztosít.

Csomagkövetelmény

A Shopify scriptek és a Script Editor alkalmazás csak a Shopify Plus-csomaggal rendelkező üzletek számára érhető el. A Script Editor alkalmazás már nem tölthető le az App Store-ból.

2026. június 30-án a Shopify scriptek eltávolításra kerülnek, és a továbbiakban nem fognak működni. Ha a meglévő Shopify scriptek használati eseteihez továbbra is támogatást szeretne, akkor a meglévő fizetési, szállítási vagy sorelem-szkripteket kompatibilis Shopify Functions helyettesítőkre kell átállítania. További információ a Shopify scriptekről a Shopify Functionsre való áttérésről.

Különböző szkripttípusok léteznek. A szkript akkor kap egy típust, amikor létrehozza azt a Script Editor alkalmazásban, attól függően, hogy melyik szkriptsablont választja kiindulásként:

Sorelem-szkriptek

A sorelem-szkriptek a kosárban lévő sorelemekre vannak hatással, és képesek az árak módosítására és kedvezmények nyújtására. Ezek a szkriptek akkor futnak le, amikor a kosárban módosítás történik.

Azok a sorelem-szkriptek, amelyek kedvezményt adnak egy előfizetésre, csak az előfizetés első fizetésére vonatkoznak. A későbbi fizetésekre a szkript nem ad kedvezményt.

Egyes metódusok csak a sorelem-szkriptekben használhatók.

Szállítási szkriptek

A szállítási szkriptek a szállítással lépnek interakcióba, és módosíthatják a szállítási módokat, valamint kedvezményeket adhatnak a szállítási díjakra. Ezek a szkriptek akkor futnak le, amikor a pénztár eléri a szállítási lehetőségek oldalt.

Azok a szállítási szkriptek, amelyek kedvezményt adnak egy előfizetés szállítási díjára, csak az előfizetés első fizetésére vonatkoznak. A későbbi fizetésekre a szkript nem ad kedvezményt.

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

Fizetési szkriptek

A fizetési szkriptek a fizetésekkel lépnek interakcióba, és átnevezhetik, elrejthetik és átrendezhetik a fizetési átjárókat. Fontos, hogy a fizetési szkriptek nem lépnek interakcióba a pénztárképernyő előtt megjelenő fizetési átjárókkal, mint például az Apple Pay. Ezek a szkriptek akkor futnak le, amikor a pénztár eléri a fizetési oldalt.

Egyes metódusok csak fizetési szkriptekben használhatók.

Általános metódusok

A következő metódusok bármilyen típusú szkriptben használhatók:

Bemenet

Szkript bemeneti metódusok

Metódus	Visszatérési típus	Leírás
.cart	Cart	Egy módosítható kosárobjektumot ad vissza.
.locale	karakterlánc	Visszaadja a vásárló területi beállítását. Például: en, fr vagy pt-BR.

Cart

A Cart objektum csak az online áruházban érhető el. Egyes elhagyott pénztárak hozzáférnek a Cart objektumhoz. Ha azonban egy pénztár lezárult, és a vásárló ezt követően felkeresi az elhagyott pénztárt, a rendszer az előre kitöltött pénztárhoz irányítja, és a Cart objektum már nem létezik. Ennek az az oka, hogy a kirakatot megkerülte az elhagyott fizetési e-mail.

Szkriptmetódusok a Cart objektum használatával

Metódus	Visszatérési típus	Leírás
.customer	Customer	Visszaadja a kosár tulajdonosát (ha van).
.shipping_address	ShippingAddress	Visszaadja a kosár tulajdonosának szállítási címét (ha van).
.discount_code	változó	Visszatérési érték: nil, ha a kosár nem rendelkezik kedvezménykóddal CartDiscount::FixedAmount, ha a kosár fix összegű kedvezménnyel rendelkezik CartDiscount::Percentage, ha a kosár százalékos kedvezménnyel rendelkezik CartDiscount::Shipping, ha a kosár szállítási kedvezménnyel rendelkezik Egyetlen kedvezménykódot ad vissza (lásd: Korlátozások) A discount_code akkor van jelen, ha kedvezményt alkalmaztak a kosárra. Ez nem feltétlenül jelenti azt, hogy a kosár ára megváltozik. Például, ha egy kedvezmény 50 USD feletti kosarakra vonatkozik, és egy szkript 50 USD alá csökkenti a kosár árát, a discount_code továbbra is jelen van, de a kosár ára nem változik. <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

Szkriptmetódusok a CartDiscount::FixedAmount objektum használatával

Metódus	Visszatérési típus	Leírás
.code	Karakterlánc	Visszaadja a kedvezmény alkalmazásához használt kedvezménykódot.
.amount	Money	Visszaadja a kedvezmény pénzbeli összegét.
.reject({ message: Karakterlánc })	nil	Elutasítja a kosárra alkalmazott kedvezménykódot. A message megadása kötelező.
.rejected?	Logikai érték	Visszaadja, hogy a kedvezménykód elutasításra került-e.

CartDiscount::Percentage

Szkriptmetódusok a CartDiscount::Percentage objektum használatával

Metódus	Visszatérési típus	Leírás
.code	Karakterlánc	Visszaadja a kedvezmény alkalmazásához használt kedvezménykódot.
.percentage	Tizedes törtszám	Visszaadja a kedvezmény százalékos mértékét.
.reject({ message: Karakterlánc })	nil	Elutasítja a kosárra alkalmazott kedvezménykódot. A message megadása kötelező.
.rejected?	Logikai érték	Visszaadja, hogy a kedvezménykód elutasításra került-e.

CartDiscount::Shipping

A CartDiscount::Shipping objektumot használó szkriptmetódusok

Metódus	Visszatérési típus	Leírás
.code	Karakterlánc	Visszaadja a kedvezmény alkalmazásához használt kedvezménykódot.
.reject({ message: Karakterlánc })	nil	Elutasítja a kosárra alkalmazott kedvezménykódot. A message megadása kötelező.
.rejected?	Logikai érték	Visszaadja, hogy a kedvezménykód elutasításra került-e.

Customer

A Customer objektumot használó szkriptmetódusok

Metódus	Visszatérési típus	Leírás
.id	Egész szám	Visszaadja a vásárló azonosítószámát.
.email	Karakterlánc	Visszaadja a vásárló e-mail-címét.
.tags	List<Tag>	A vásárlóhoz beállított címkéket jelölő karakterláncokból álló listát ad vissza.
.orders_count	Egész szám	Visszaadja a vásárló által leadott rendelések teljes számát.
.total_spent	Money	Visszaadja a teljes összeget, amelyet a vásárló az összes rendelésére költött.
.accepts_marketing?	Logikai érték	Azt adja vissza, hogy a vásárló elfogadja-e a marketingcélú megkereséseket.

LineItem

A LineItem objektumot használó szkriptmetódusok

Metódus	Visszatérési típus	Leírás
.grams	gramm	Visszaadja a sorelem teljes súlyát.
.line_price	Money	A sorelem ára.
.discounted?	Logikai érték	Azt adja vissza, hogy egy sorelem árát csökkentette-e egy szkript vagy egy manuálisan alkalmazott kedvezmény. A kedvezménykódok használata nem befolyásolja a visszatérési értéket.
.properties	hash	Visszaadja az ehhez a sorelemhez megadott tulajdonságokat.
.variant	Variant	Visszaadja azt a konkrét termékváltozatot, amelyet a sorelem képvisel.
.quantity	Egész szám	Visszaadja ennek a sorelemnek a mennyiségét.
.selling_plan_id	Egész szám	Visszaadja a sorelemhez tartozó értékesítési terv azonosítóját. Ez a metódus akkor hasznos, ha az üzlet előfizetéseket értékesít, és azt szeretné, hogy a szkript észlelje, amikor egy termékváltozatot előfizetésként értékesítenek.

List

A List objektumot használó szkriptmetódusok

Metódus	Visszatérési típus	Leírás
.new	List	Új objektumot hoz létre egy lista ábrázolásához.
.[]	Elem vagy nil	Visszaadja a megadott indexen lévő elemet.
.&	List	Új listát ad vissza, amely a két listában közös elemeket tartalmazza, duplikátumok nélkül.
.delete_if	List	Elemeket töröl egy opcionális kódblokk használatával. Lásd a Ruby delete_if metódusának dokumentációját.
.empty?	Logikai érték	true értéket ad vissza, ha a lista nem tartalmaz elemeket.
.first	Elem vagy nil	Visszaadja az első elemet, vagy nil értéket, ha a lista üres.
.index(*args, &block)	int vagy nil	Visszaadja a lista első elemének indexét. Ha argumentum helyett egy blokkot adnak meg, akkor annak az első elemnek az indexét adja vissza, amelyre a blokk igaz.
.rindex(*args, &block)	int vagy nil	Visszaadja a lista utolsó elemének indexét. Ha argumentum helyett egy blokkot adnak meg, akkor annak az első elemnek az indexét adja vissza, amelyre a blokk igaz.
.last	Elem vagy nil	Visszaadja az utolsó elemet, vagy nil értéket, ha a lista üres.
.length	int	Visszaadja a listában lévő elemek számát.
.size	int	A length aliasa.
.each(*args, &block)	List	A lista minden elemére egyszer meghív egy blokkot, paraméterként átadva az elemet a blokknak.

ShippingAddress

A ShippingAddress objektumot használó szkriptmetódusok

Metódus	Visszatérési típus	Leírás
.name	karakterlánc	Visszaadja a szállítási címhez társított személy nevét.
.address1	karakterlánc	Visszaadja a szállítási cím utca és házszám részét.
.address2	karakterlánc	Visszaadja a szállítási cím utca és házszám részének opcionális kiegészítő mezőjét.
.phone	karakterlánc	Visszaadja a szállítási címhez tartozó telefonszámot.
.city	karakterlánc	Visszaadja a szállítási címhez tartozó várost.
.zip	karakterlánc	Visszaadja a szállítási cím irányítószámát.
.province	karakterlánc	Visszaadja a szállítási cím tartományát/államát.
.province_code	karakterlánc	Visszaadja a szállítási cím tartományának/államának rövidített értékét.
.country_code	karakterlánc	Visszaadja a szállítási cím országának rövidített értékét.

Money

A Money objektumot használó szkriptmetódusok

Metódus	Visszatérési típus	Leírás
.derived_from_presentment(customer_cents:X)	Money	Átvált egy összeget (centben) a vásárló helyi (megjelenített) valutájáról az áruházad valutájára. A metódus elfogadja a customer_cents paramétert, amely egy centben megadott számot fogad el. Például: Money.derived_from_presentment(customer_cents: 500).
.new	Money	Új objektumot hoz létre, amely egy árat képvisel.
.zero	Money	Új objektumot hoz létre nulla értékű árral.
+	Money	Összead két Money objektumot.
-	Money	Kivon egy Money objektumot egy másikból.
*	Money	Megszoroz egy Money objektumot egy számmal.

Money – példák

Money.new(cents: 1000)

Létrehoz egy Money objektumot, amely 1000 centet, azaz 10 dollárt képvisel.

Money.new(cents: 100) * 50

Létrehoz egy 1 dollárt képviselő Money objektumot, majd megszorozza ezt az összeget 50-nel. Egy 50 dollárt képviselő Money objektumot ad vissza.

Változat

A Variant objektumot használó szkriptmetódusok

Metódus	Visszatérési típus	Leírás
.id	Egész szám	A változat azonosítóját adja vissza.
.price	Money	A változat egységárát adja vissza.
.product	Product	A változathoz tartozó terméket adja vissza.
.skus	List<String>	A változat cikkszámait (SKU) adja vissza, amelyeket gyakran használnak a készletkövetéshez.
.title	Karakterlánc	A változat címét adja vissza.

Termék

A Product objektumot használó szkriptmetódusok

Metódus	Visszatérési típus	Leírás
.id	Egész szám	A termék azonosítószámát adja vissza.
.gift_card?	Logikai érték	Visszaadja, hogy a termék ajándékkártya-e.
.tags	List<Tag>	Visszaadja a termékhez beállított címkéket karakterláncok listájaként.
.product_type	Karakterlánc	Egy kategorizálás, amellyel egy terméket fel lehet címkézni, és amelyet általában szűrésre és keresésre használnak.
.vendor	Karakterlánc	A termék szállítóját adja vissza.

Kernel

A Kernel egy Ruby-modul, amely minden osztályban megtalálható. Ennek eredményeként a metódusai minden objektum számára elérhetők. Ezek a metódusok ugyanúgy működnek, mint a globális függvények más nyelvekben.

A Kernel objektumot használó szkriptmetódusok

Metódus	Visszatérési típus	Leírás
.exit	nincs	Hiba nélkül leállítja az aktuális szkript végrehajtását. Ha azelőtt fut, hogy bármi is hozzá lenne rendelve az Output.cart-hoz, a szkriptnek nincs hatása. Ez egy hasznos módja a szkriptekből való kilépésnek, például ha a vásárló nem jogosult a szkript futtatására.

Kernel – példa

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

Sorelemmetódusok

A következő metódusok csak sorelem-szkriptekben használhatók:

Cart

A Cart objektumot használó szkriptmetódusok sorelem-szkriptekben

Metódus	Visszatérési típus	Leírás
.subtotal_price_was	Money	A kosár kedvezmények alkalmazása előtti részösszegét adja vissza.
.subtotal_price_changed?	Logikai érték	Azt adja vissza, hogy a részösszeg megváltozott-e.

LineItem

A LineItem objektumot használó szkriptmetódusok sorelem-szkriptekben

Metódus	Visszatérési típus	Leírás
.change_line_price(Money new_price, { message: String })	Money	Módosítja a sorelem árát a megadott összegre. A message megadása kötelező. A new_price összegnek alacsonyabbnak kell lennie a jelenlegi árnál.
.original_line_price	Money	A sorelem eredeti árát adja vissza a szkriptek és kedvezmények alkalmazása előtt.
.line_price_was	Money	A sorelem árát adja vissza az aktuális szkript által végrehajtott módosítások előtt.
.line_price_changed?	Logikai érték	Visszaadja, hogy a sorelem ára megváltozott-e.
.change_properties(hash new_properties, { message: String })	hash	Új tulajdonságokat állít be egy sorelemhez. Az eredeti tulajdonságokat tartalmazó hash a properties_was változóban tárolódik, a metódusnak átadott hash pedig a sorelem új tulajdonságait tartalmazza majd.
.properties_was	hash	A sorelem eredeti tulajdonság-hash-ét adja vissza a módosítások alkalmazása előtt.
.properties_changed?	Logikai érték	Visszaadja, hogy a sorelem tulajdonságai megváltoztak-e.
.split({ take: Integer })	LineItem	Egy sorelemet két sorelemre oszt. A take paraméter határozza meg, hogy az új sorelem létrehozásához mekkora mennyiséget kell eltávolítani az eredetiből.

.split – példa

Ez a példaszkript egy original_line_item nevű sorelemet két sorelemre oszt. Az új sorelem mennyisége 1 (ezt a take: 1 paraméter adja meg). A szkript ezután kedvezményes árat alkalmaz az új sorelemre a „Third hat for 5 dollars” üzenettel.

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

Változat

A Variant objektumot használó szkriptmetódusok sorelem-szkriptekben

Metódus	Visszatérési típus	Leírás
.compare_at_price	Money	A változat eredeti árát adja vissza. Ha a változatnak nincs eredeti ára, akkor nil értéket ad vissza.

Szállítási módok

A következő metódusok szállítási szkriptekben használhatók:

Bemenet

Az Input objektumot használó szkriptmetódusok szállítási szkriptekben

Metódus	Visszatérési típus	Leírás
.shipping_rates	ShippingRateList	Visszaadja az összes szállítási díj listáját.

ShippingRateList

A ShippingRateList objektumot használó szkriptmetódusok a szállítási szkriptekben

Metódus	Visszatérési típus	Leírás
.delete_if	ShippingRateList	Szállítási díjak törlése egy opcionális kódblokk használatával. Lásd a Ruby delete_if metódusának dokumentációját.
.sort!	ShippingRateList	A szállítási díjak rendezése az összehasonlító operátor vagy egy opcionális kódblokk használatával. Lásd a Ruby sort! metódusának dokumentációját.
.sort_by!	ShippingRateList	A szállítási díjak rendezése egy opcionális kódblokk használatával. Lásd a Ruby sort_by! metódusának dokumentációját.

ShippingRate

A ShippingRate objektumot használó szkriptmetódusok a szállítási szkriptekben

Metódus	Visszatérési típus	Leírás
.code	Karakterlánc	Visszaadja a szállítási díj kódját.
.markup	Money	Visszaadja a szállítási díj árrését, ha van ilyen.
.name	Karakterlánc	Visszaadja a szállítási díj nevét. A change_name metódussal módosítható.
.price	Money	Visszaadja a szállítási díj árát.
.source	Karakterlánc	Visszaadja a szállítási díjhoz tartozó forrást (a fuvarozót), ha releváns. Nem módosítható.
.change_name(String new_name)	Karakterlánc	Módosítja a szállítási díj nevét (maximum 255 karakter). A forrást nem lehet módosítani, törölni vagy elrejteni.
.apply_discount(Money discount, { message: String })	Money	A megadott fix összegű kedvezményt alkalmazza. Az ár nem csökkenthető 0 alá. Üzenet megadása kötelező.
.phone_required?	Logikai érték	true értéket ad vissza, ha a szállítási díjhoz telefonszám szükséges, vagy false értéket, ha nem szükséges telefonszám.

Fizetési módok

A következő metódusok használhatók a fizetési szkriptekben:

Bemenet

Az Input objektumot használó szkriptmetódusok a fizetési szkriptekben

Metódus	Visszatérési típus	Leírás
.payment_gateways	PaymentGatewaysList	Visszaadja az üzlet összes fizetési átjárójának listáját.

PaymentGatewayList

A PaymentGatewayList objektumot használó szkriptmetódusok a fizetési szkriptekben

Metódus	Visszatérési típus	Leírás
.delete_if	PaymentGatewayList	Fizetési átjárók törlése egy opcionális kódblokk használatával. Lásd a Ruby delete_if metódusának dokumentációját.
.sort!	PaymentGatewayList	A fizetési átjárók rendezése az összehasonlító operátor vagy egy opcionális kódblokk használatával. Lásd a Ruby sort! metódusának dokumentációját.
.sort_by!	PaymentGatewayList	A fizetési átjárók rendezése egy opcionális kódblokk használatával. Lásd a Ruby sort_by! metódusának dokumentációját.

PaymentGateway

Metódus	Visszatérési típus	Leírás
.name	Karakterlánc	Visszaadja a fizetési átjáró nevét.
.enabled_card_brands	List<String>	Ha a fizetési átjáró támogatja a bankkártyákat, visszaadja az üzlet által elfogadott bankkártyatípusok listáját. Ha az átjáró nem támogatja a bankkártyákat, üres listát ad vissza.
.change_name(String new_name)	Karakterlánc	Módosítja a fizetési átjáró nevét. A logóval rendelkező fizetési átjárókat nem lehet átnevezni.

Példák

A következő sorelem szkript példában, amikor egy vásárló olyan terméket rendel, amely nem ajándékkártya, a termék ára 9 dollárral csökken. Ezenkívül megjelenik a teljes összeg, amelyet a vásárló az üzletében tett összes látogatása során elköltött:

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

További információ

További információ a következőkről:

• A Ruby alapjai
• Szkriptek létrehozása
• A szkriptek tesztelése és hibakeresése
• A Liquid-sablonok frissítése a szkriptekhez
• Shopify scriptek