Referenčná príručka rozhrania API pre Skripty Shopify

Skripty sa píšu pomocou rozhrania Ruby API, ktoré vám poskytuje veľkú mieru kontroly a flexibility.

Požiadavka na plán

Skripty Shopify a aplikácia Script Editor sú dostupné len pre obchody s plánom Shopify Plus. Aplikáciu Script Editor už nie je možné stiahnuť zo Shopify App Store.

30. júna 2026 sa Skripty Shopify odstránia a prestanú fungovať. Ak chcete naďalej podporovať svoje existujúce prípady použitia Skriptov Shopify, musíte prejsť na kompatibilné náhrady v Shopify Functions pre vaše existujúce skripty platieb, dopravy alebo samostatných položiek. Získajte ďalšie informácie o prechode zo Skriptov Shopify na Shopify Functions.

Existujú rôzne typy skriptov. Typ sa skriptu priradí pri jeho vytvorení v aplikácii Script Editor na základe toho, s akou šablónou skriptu začnete:

Skripty pre samostatné položky

Skripty pre samostatné položky ovplyvňujú samostatné položky v košíku a môžu meniť ceny a poskytovať zľavy. Tieto skripty sa spustia po vykonaní zmeny v košíku.

Skripty pre samostatné položky, ktoré uplatňujú zľavu na predplatné, sa aplikujú iba na prvú platbu za predplatné. Skript na nasledujúce platby zľavu neuplatní.

Niektoré metódy možno použiť iba v skriptoch pre samostatné položky.

Skripty pre dopravu

Skripty pre dopravu interagujú s dopravou a môžu zmeniť spôsoby dopravy a poskytnúť zľavy na sadzby za dopravu. Tieto skripty sa spúšťajú, keď sa v pokladni prejde na stránku s možnosťami dopravy.

Skripty pre dopravu, ktoré uplatňujú zľavu na sadzbu za dopravu pre predplatné, sa aplikujú iba na prvú platbu za predplatné. Skript na nasledujúce platby zľavu neuplatní.

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

Platobné skripty

Platobné skripty interagujú s platbami a môžu premenovať, skryť a zmeniť poradie platobných brán. Upozorňujeme, že platobné skripty neinteragujú s platobnými bránami zobrazenými pred obrazovkou pokladne, ako je napríklad Apple Pay. Tieto skripty sa spúšťajú, keď sa v pokladni prejde na stránku platby.

Niektoré metódy možno použiť iba v platobných skriptoch.

Všeobecné metódy

Nasledujúce metódy sa dajú použiť v akomkoľvek type skriptu:

Vstup

Vstupné metódy skriptu

Metóda	Návratový typ	Popis
.cart	Cart	Vráti meniteľný objekt košíka.
.locale	reťazec	Vráti jazyk a región zákazníka. Napríklad en, fr alebo pt-BR.

Cart

Objekt košíka je dostupný iba v online obchode. Niektoré opustené pokladne majú k objektu košíka prístup. Ak sa však pokladňa zatvorí a zákazník následne navštívi opustenú pokladňu, presmeruje ho do vopred vyplnenej pokladne a objekt košíka prestane existovať. Stane sa tak preto, lebo e-mail o opustenej pokladni obíde výkladnú skriňu.

Metódy skriptu, ktoré používajú objekt Cart

Metóda	Návratový typ	Popis
.customer	Customer	Vráti vlastníka košíka (ak existuje).
.shipping_address	ShippingAddress	Vráti dodaciu adresu vlastníka košíka (ak existuje).
.discount_code	rôzne	Vráti: nil, ak v košíku nie je zľavový kód CartDiscount::FixedAmount, ak má košík pevnú sumu zľavy CartDiscount::Percentage, ak má košík percentuálnu zľavu CartDiscount::Shipping, ak má košík zľavu na dopravu Vráti jeden zľavový kód (pozrite časť Obmedzenia) discount_code je prítomný, ak bola na košík uplatnená zľava. Nemusí to nevyhnutne znamenať, že sa cena košíka zmení. Ak sa zľava uplatňuje napríklad na košíky nad 50 $ a skript zníži cenu košíka pod 50 $, discount_code bude naďalej prítomný, ale cena košíka sa nezmení. <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

Metódy skriptu, ktoré používajú objekt CartDiscount::FixedAmount

Metóda	Návratový typ	Popis
.code	Reťazec	Vráti zľavový kód použitý na uplatnenie zľavy.
.amount	Money	Vráti peňažnú sumu zľavy.
.reject({ message: String })	nil	Odmietne zľavový kód uplatnený na košík. Vyžaduje sa message.
.rejected?	Booleovská hodnota	Vráti informáciu o tom, či bol zľavový kód odmietnutý.

CartDiscount::Percentage

Metódy skriptu, ktoré používajú objekt CartDiscount::Percentage

Metóda	Návratový typ	Popis
.code	Reťazec	Vráti zľavový kód použitý na uplatnenie zľavy.
.percentage	Desatinné číslo	Vráti percentuálnu výšku zľavy.
.reject({ message: String })	nil	Odmietne zľavový kód uplatnený na košík. Vyžaduje sa message.
.rejected?	Booleovská hodnota	Vráti informáciu o tom, či bol zľavový kód odmietnutý.

CartDiscount::Shipping

Metódy skriptu, ktoré používajú objekt CartDiscount::Shipping

Metóda	Návratový typ	Popis
.code	Reťazec	Vráti zľavový kód použitý na uplatnenie zľavy.
.reject({ message: String })	nil	Odmietne zľavový kód uplatnený na košík. Vyžaduje sa message.
.rejected?	Booleovská hodnota	Vráti informáciu o tom, či bol zľavový kód odmietnutý.

Customer

Metódy skriptu, ktoré používajú objekt Customer

Metóda	Návratový typ	Popis
.id	Celé číslo	Vráti ID číslo zákazníka.
.email	Reťazec	Vráti e-mailovú adresu zákazníka.
.tags	List<Tag>	Vráti zoznam reťazcov, ktoré predstavujú všetky štítky nastavené pre zákazníka.
.orders_count	Celé číslo	Vráti celkový počet objednávok, ktoré zákazník zadal.
.total_spent	Money	Vráti celkovú sumu, ktorú zákazník minul na všetky objednávky.
.accepts_marketing?	Booleovská hodnota	Vráti informáciu o tom, či zákazník súhlasí s marketingom.

LineItem

Metódy skriptu používajúce objekt LineItem

Metóda	Návratový typ	Popis
.grams	gramy	Vráti celkovú hmotnosť samostatnej položky.
.line_price	Money	Cena samostatnej položky.
.discounted?	Booleovská hodnota	Vráti informáciu o tom, či bola cena samostatnej položky znížená skriptom alebo manuálne uplatnenou zľavou. Použitie zľavových kódov nemá vplyv na vrátenú hodnotu.
.properties	hash	Vráti vlastnosti, ktoré sa zadali pre túto samostatnú položku.
.variant	Variant	Vráti konkrétny variant produktu, ktorý predstavuje samostatná položka.
.quantity	Celé číslo	Vráti množstvo tejto samostatnej položky.
.selling_plan_id	Celé číslo	Vráti ID plánu predaja pre samostatnú položku. Táto metóda je užitočná, keď obchod predáva predplatné a chcete, aby skript zistil, kedy sa variant produktu predáva ako predplatné.

List

Metódy skriptu používajúce objekt List

Metóda	Návratový typ	Popis
.new	List	Vytvorí nový objekt, ktorý predstavuje zoznam.
.[]	Prvok alebo nil	Vráti prvok na zadanom indexe.
.&	List	Vráti nový zoznam obsahujúci prvky spoločné pre oba zoznamy bez duplikátov.
.delete_if	List	Odstráni prvky pomocou voliteľného bloku kódu. Pozrite si dokumentáciu k metóde delete_if v jazyku Ruby.
.empty?	Booleovská hodnota	Vráti hodnotu true, ak zoznam neobsahuje žiadne prvky.
.first	Prvok alebo nil	Vráti prvý prvok alebo nil, ak je zoznam prázdny.
.index(*args, &block)	int alebo nil	Vráti index prvého prvku zoznamu. Ak sa namiesto argumentu zadá blok, vráti index prvého prvku, pre ktorý má blok hodnotu true.
.rindex(*args, &block)	int alebo nil	Vráti index posledného prvku zoznamu. Ak sa namiesto argumentu zadá blok, vráti index prvého prvku, pre ktorý má blok hodnotu true.
.last	Prvok alebo nil	Vráti posledný prvok alebo nil, ak je zoznam prázdny.
.length	int	Vráti počet prvkov v zozname.
.size	int	Alias pre length.
.each(*args, &block)	List	Zavolá blok raz pre každý prvok v zozname, pričom do bloku odovzdá prvok ako parameter.

ShippingAddress

Metódy skriptu používajúce objekt ShippingAddress

Metóda	Návratový typ	Popis
.name	reťazec	Vráti meno osoby spojenej s dodacou adresou.
.address1	reťazec	Vráti časť s ulicou z dodacej adresy.
.address2	reťazec	Vráti voliteľné dodatočné pole k časti s ulicou z dodacej adresy.
.phone	reťazec	Vráti telefónne číslo z dodacej adresy.
.city	reťazec	Vráti mesto z dodacej adresy.
.zip	reťazec	Vráti PSČ z dodacej adresy.
.province	reťazec	Vráti kraj/štát z dodacej adresy.
.province_code	reťazec	Vráti skrátenú hodnotu kraja/štátu z dodacej adresy.
.country_code	reťazec	Vráti skrátenú hodnotu krajiny z dodacej adresy.

Money

Metódy skriptu používajúce objekt Money

Metóda	Návratový typ	Popis
.derived_from_presentment(customer_cents:X)	Money	Konvertuje sumu (v centoch) z miestnej (zobrazovanej) meny zákazníka na menu vášho obchodu. Táto metóda prijíma parameter customer_cents, ktorý prijíma číslo v centoch. Napríklad Money.derived_from_presentment(customer_cents: 500).
.new	Money	Vytvorí nový objekt, ktorý predstavuje cenu.
.zero	Money	Vytvorí nový objekt s nulovou cenou.
+	Money	Spočíta dva objekty Money.
-	Money	Odpočíta jeden objekt Money od druhého.
*	Money	Vynásobí objekt Money číslom.

Príklady objektu Money

Money.new(cents: 1000)

Vytvorí objekt Money, ktorý predstavuje 1 000 centov, teda 10 $.

Money.new(cents: 100) * 50

Vytvorí objekt Money predstavujúci 1 $, následne túto sumu vynásobí číslom 50. Vráti objekt Money predstavujúci 50 $.

Variant

Metódy skriptu používajúce objekt Variant

Metóda	Návratový typ	Popis
.id	Celé číslo	Vráti číslo ID variantu.
.price	Money	Vráti jednotkovú cenu variantu.
.product	Product	Vráti priradený produkt variantu.
.skus	List<String>	Vráti skladové jednotky (SKU) variantu, ktoré sa často používajú na sledovanie inventára.
.title	Reťazec	Vráti názov variantu.

Produkt

Metódy skriptu používajúce objekt Product

Metóda	Návratový typ	Popis
.id	Celé číslo	Vráti číslo ID produktu.
.gift_card?	Booleovská hodnota	Vráti informáciu o tom, či je produkt darčeková karta.
.tags	List<Tag>	Vráti zoznam reťazcov predstavujúcich štítky, ktoré sú nastavené pre tento produkt.
.product_type	Reťazec	Kategorizácia, ktorou je možné produkt označiť. Bežne sa používa na filtrovanie a vyhľadávanie.
.vendor	Reťazec	Vráti dodávateľa tohto produktu.

Kernel

Kernel je modul jazyka Ruby, ktorý je súčasťou každej triedy. Vďaka tomu sú jeho metódy k dispozícii pre každý objekt. Tieto metódy fungujú rovnako ako globálne funkcie v iných jazykoch.

Metódy skriptu používajúce objekt Kernel

Metóda	Návratový typ	Popis
.exit	žiadne	Ukončí vykonávanie aktuálneho skriptu bez chyby. Ak sa to spustí predtým, ako sa niečo priradí do Output.cart, skript nebude mať žiadny vplyv. Toto je užitočný spôsob ukončenia skriptov, napríklad ak zákazník nemá oprávnenie na spustenie skriptu.

Príklad modulu Kernel

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

Metódy pre samostatné položky

Nasledujúce metódy možno použiť iba v skriptoch samostatných položiek:

Cart

Metódy skriptu používajúce objekt Cart v skriptoch samostatných položiek

Metóda	Návratový typ	Popis
.subtotal_price_was	Money	Vráti medzisúčet košíka pred uplatnením akýchkoľvek zliav.
.subtotal_price_changed?	Booleovská hodnota	Vráti informáciu o tom, či sa medzisúčet zmenil.

LineItem

Metódy skriptu používajúce objekt LineItem v skriptoch samostatných položiek

Metóda	Návratový typ	Popis
.change_line_price(Money new_price, { message: String })	Money	Zmení cenu samostatnej položky na zadanú sumu. Vyžaduje sa argument message. Hodnota new_price musí byť nižšia ako aktuálna cena.
.original_line_price	Money	Vráti pôvodnú cenu samostatnej položky pred uplatnením skriptov a zliav.
.line_price_was	Money	Vráti cenu samostatnej položky pred uplatnením zmien aktuálnym skriptom.
.line_price_changed?	Booleovská hodnota	Vráti informáciu o tom, či sa zmenila cena samostatnej položky.
.change_properties(hash new_properties, { message: String })	hash	Nastaví nové vlastnosti pre samostatnú položku. Pôvodný hash vlastností je uložený v properties_was a z hashu vlastností odovzdaného metóde sa stanú nové vlastnosti pre samostatnú položku.
.properties_was	hash	Vráti pôvodný hash vlastností samostatnej položky pred uplatnením akýchkoľvek zmien.
.properties_changed?	Booleovská hodnota	Vráti informáciu o tom, či sa zmenili vlastnosti samostatnej položky.
.split({ take: Integer })	LineItem	Rozdelí samostatnú položku na dve samostatné položky. Argument take určuje, aké množstvo sa má odstrániť z pôvodnej samostatnej položky na vytvorenie novej.

Príklad metódy .split

Tento vzorový skript rozdelí samostatnú položku s názvom original_line_item na dve samostatné položky. Nová samostatná položka má množstvo 1 (určené argumentom take: 1). Skript potom uplatní zľavnenú cenu na novú samostatnú položku so správou „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

Variant

Metódy skriptu používajúce objekt Variant v skriptoch samostatných položiek

Metóda	Návratový typ	Popis
.compare_at_price	Money	Vráti porovnávaciu cenu variantu. Vráti nil, ak variant nemá porovnávaciu cenu.

Metódy pre dopravu

Nasledujúce metódy možno použiť v skriptoch dopravy:

Vstup

Metódy skriptu používajúce objekt Input v skriptoch dopravy

Metóda	Návratový typ	Popis
.shipping_rates	ShippingRateList	Vráti zoznam všetkých sadzieb za dopravu.

ShippingRateList

Metódy skriptu používajúce objekt ShippingRateList v skriptoch dopravy

Metóda	Návratový typ	Popis
.delete_if	ShippingRateList	Odstráni sadzby za dopravu pomocou voliteľného bloku kódu. Pozrite si dokumentáciu pre metódu delete_if v jazyku Ruby.
.sort!	ShippingRateList	Zoradí sadzby za dopravu pomocou operátora porovnania alebo voliteľného bloku kódu. Pozrite si dokumentáciu pre metódu sort! v jazyku Ruby.
.sort_by!	ShippingRateList	Zoradí sadzby za dopravu pomocou voliteľného bloku kódu. Pozrite si dokumentáciu pre metódu sort_by! v jazyku Ruby.

ShippingRate

Metódy skriptu používajúce objekt ShippingRate v skriptoch dopravy

Metóda	Návratový typ	Popis
.code	Reťazec	Vráti kód sadzby za dopravu.
.markup	Money	Vráti značky pre sadzbu za dopravu, ak je to uplatniteľné.
.name	Reťazec	Vráti názov sadzby za dopravu. Je možné ho upraviť pomocou metódy change_name.
.price	Money	Vráti cenu sadzby za dopravu.
.source	Reťazec	Vráti zdroj (prepravcu) priradený k sadzbe za dopravu, ak je to relevantné. Nemožno ho upraviť.
.change_name(String new_name)	Reťazec	Zmení názov sadzby za dopravu (maximálne 255 znakov). Zdroj nie je možné zmeniť, odstrániť ani skryť.
.apply_discount(Money discount, { message: String })	Money	Uplatní zľavu v zadanej pevnej sume. Cenu nemožno znížiť pod nulu. Vyžaduje sa správa.
.phone_required?	Booleovská hodnota	Vráti true, ak sa na získanie sadzby za dopravu vyžaduje telefónne číslo, alebo false, ak sa telefónne číslo nevyžaduje.

Spôsoby platby

Nasledujúce metódy sa dajú použiť v platobných skriptoch:

Vstup

Metódy skriptov používajúce objekt Input v platobných skriptoch

Metóda	Návratový typ	Popis
.payment_gateways	PaymentGatewaysList	Vráti zoznam všetkých platobných brán v obchode.

PaymentGatewayList

Metódy skriptov používajúce objekt PaymentGatewayList v platobných skriptoch

Metóda	Návratový typ	Popis
.delete_if	PaymentGatewayList	Odstráni platobné brány pomocou voliteľného bloku kódu. Pozrite si dokumentáciu pre metódu delete_if v jazyku Ruby.
.sort!	PaymentGatewayList	Zoradí platobné brány pomocou operátora porovnania alebo pomocou voliteľného bloku kódu. Pozrite si dokumentáciu pre metódu sort! v jazyku Ruby.
.sort_by!	PaymentGatewayList	Zoradí platobné brány pomocou voliteľného bloku kódu. Pozrite si dokumentáciu pre metódu sort_by! v jazyku Ruby.

PaymentGateway

Metóda	Návratový typ	Popis
.name	Reťazec	Vráti názov platobnej brány.
.enabled_card_brands	List<String>	Ak platobná brána podporuje kreditné karty, vráti zoznam typov kreditných kariet, ktoré obchod akceptuje. Ak brána nepodporuje kreditné karty, vráti prázdny zoznam.
.change_name(String new_name)	Reťazec	Zmení názov platobnej brány. Platobné brány s logami nemožno premenovať.

Príklady

V nasledujúcom príklade skriptu samostatnej položky sa pri objednávke produktu, ktorý nie je darčekovou kartou, zníži cena tohto produktu o 9 $. Taktiež sa zobrazí celková suma, ktorú zákazník minul počas všetkých návštev vášho obchodu:

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

Ďalšie informácie

Ďalšie informácie o témach:

• Základy jazyka Ruby
• Vytváranie skriptov
• Testovanie a ladenie skriptov
• Aktualizácia šablón Liquid pre skripty
• Skripty Shopify