Shopify Scripts -API-viite

Komentosarjat kirjoitetaan Ruby-API:lla, joka antaa sinulle paljon hallintamahdollisuuksia ja joustavuutta.

Sopimusvaatimus

Shopify Scripts ja Script Editor -sovellus ovat saatavilla vain Shopify Plus -sopimuksen kaupoille. Script Editor -sovellus ei ole enää ladattavissa Shopify App Storesta.

Shopify Scripts poistetaan käytöstä 30. kesäkuuta 2026, minkä jälkeen ne eivät enää toimi. Jos haluat jatkaa nykyisten Shopify Scripts -komentosarjojesi käyttöä, sinun on siirryttävä yhteensopiviin Shopify Functions -korvaajiin nykyisille maksu-, toimitus- tai rivikohtakomentosarjoillesi. Lue lisää siirtymisestä Shopify Scriptsistä Shopify Functionsiin.

Komentosarjoja on erilaisia. Komentosarjalle määritetään tyyppi, kun luot sen Script Editor -sovelluksessa. Tyyppi perustuu siihen, minkä komentosarjamallin valitset aloitukseksi:

Rivikohtien komentosarjat

Rivikohtien komentosarjat vaikuttavat ostoskorin rivikohtiin, ja niillä voi muuttaa hintoja ja myöntää alennuksia. Nämä komentosarjat suoritetaan, kun ostoskoriin tehdään muutos.

Toistuvan tilauksen hintaa alentavat rivikohtien komentosarjat koskevat vain tilauksen ensimmäistä maksua. Komentosarja ei alenna myöhempiä maksuja.

Joitakin metodeja voi käyttää vain rivikohtien komentosarjoissa.

Toimituksen komentosarjat

Toimituksen komentosarjat ovat vuorovaikutuksessa toimituksen kanssa, ja niillä voi muuttaa toimitustapoja ja myöntää alennuksia toimitushintoihin. Nämä komentosarjat suoritetaan, kun kassalla siirrytään toimitusvaihtoehtojen sivulle.

Toistuvan tilauksen toimitushintaa alentavat toimituksen komentosarjat koskevat vain tilauksen ensimmäistä maksua. Komentosarja ei alenna myöhempiä maksuja.

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

Maksujen komentosarjat

Maksujen komentosarjat ovat vuorovaikutuksessa maksujen kanssa, ja niillä voi nimetä uudelleen, piilottaa ja järjestää uudelleen maksuportaaleja. Huomaa, että maksujen komentosarjat eivät ole vuorovaikutuksessa maksuportaalien kanssa, jotka näytetään ennen kassanäyttöä, kuten Apple Pay. Nämä komentosarjat suoritetaan, kun kassalla siirrytään maksusivulle.

Joitakin metodeja voi käyttää vain maksujen komentosarjoissa.

Yleiset metodit

Seuraavia metodeja voi käyttää kaikentyyppisissä komentosarjoissa:

Syöte

Komentosarjan syötemetodit

Metodi	Palautustyyppi	Kuvaus
.cart	Ostoskori	Palauttaa muokattavan ostoskori-objektin.
.locale	merkkijono	Palauttaa asiakkaan alueen. Esimerkiksi en, fr tai pt-BR.

Ostoskori

Ostoskori-objekti on saatavilla vain verkkokaupassa. Joissakin hylätyissä kassavaiheissa on pääsy ostoskori-objektiin. Jos kassa on kuitenkin suljettu ja asiakas siirtyy hylättyyn kassavaiheeseen, hänet ohjataan esitäytettyyn kassaan, eikä ostoskori-objektia enää ole olemassa. Tämä johtuu siitä, että myyntipaikka on ohitettu hylätystä ostoskorista lähetetyn sähköpostin avulla.

Komentosarjan metodit, jotka käyttävät Ostoskori-objektia

Metodi	Palautustyyppi	Kuvaus
.customer	Asiakas	Palauttaa ostoskorin omistajan (jos sellainen on).
.shipping_address	Toimitusosoite	Palauttaa ostoskorin omistajan toimitusosoitteen (jos sellainen on).
.discount_code	vaihtelee	Palauttaa: nil, jos ostoskorissa ei ole alennuskoodia CartDiscount::FixedAmount, jos ostoskorissa on kiinteä alennussumma CartDiscount::Percentage, jos ostoskorissa on prosentuaalinen alennus CartDiscount::Shipping, jos ostoskorissa on toimitusalennus Palauttaa yhden alennuskoodin (katso Rajoitukset) discount_code on olemassa, jos ostoskoriin on sovellettu alennusta. Tämä ei välttämättä tarkoita, että ostoskorin hinta muuttuu. Jos esimerkiksi alennus koskee yli 50 dollarin ostoskoreja ja komentosarja laskee ostoskorin hinnan alle 50 dollariin, discount_code on edelleen olemassa, mutta ostoskorin hinta ei muutu. <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

Komentosarjan metodit, jotka käyttävät CartDiscount::FixedAmount-objektia

Metodi	Palautustyyppi	Kuvaus
.code	Merkkijono	Palauttaa alennuksen soveltamiseen käytetyn alennuskoodin.
.amount	Raha	Palauttaa alennuksen rahamäärän.
.reject({ message: Merkkijono })	nil	Hylkää ostoskoriin sovelletun alennuskoodin. message on pakollinen.
.rejected?	Boolen arvo	Palauttaa tiedon siitä, onko alennuskoodi hylätty.

CartDiscount::Percentage

Komentosarjan metodit, jotka käyttävät CartDiscount::Percentage-objektia

Metodi	Palautustyyppi	Kuvaus
.code	Merkkijono	Palauttaa alennuksen soveltamiseen käytetyn alennuskoodin.
.percentage	Desimaaliluku	Palauttaa alennuksen prosenttimäärän.
.reject({ message: Merkkijono })	nil	Hylkää ostoskoriin sovelletun alennuskoodin. message on pakollinen.
.rejected?	Boolen arvo	Palauttaa tiedon siitä, onko alennuskoodi hylätty.

CartDiscount::Shipping

CartDiscount::Shipping-olion skriptimenetelmät

Metodi	Palautustyyppi	Kuvaus
.code	Merkkijono	Palauttaa alennuksen soveltamiseen käytetyn alennuskoodin.
.reject({ message: Merkkijono })	nil	Hylkää ostoskoriin sovelletun alennuskoodin. message on pakollinen.
.rejected?	Boolen arvo	Palauttaa tiedon siitä, onko alennuskoodi hylätty.

Asiakas

Asiakas-olion skriptimenetelmät

Metodi	Palautustyyppi	Kuvaus
.id	Kokonaisluku	Palauttaa asiakkaan tunnuksen.
.email	Merkkijono	Palauttaa asiakkaan sähköpostiosoitteen.
.tags	List<Tag>	Palauttaa luettelon merkkijonoja, jotka vastaavat asiakkaalle asetettuja tunnisteita.
.orders_count	Kokonaisluku	Palauttaa asiakkaan tekemien tilausten kokonaismäärän.
.total_spent	Raha	Palauttaa kokonaissumman, jonka asiakas on käyttänyt kaikkiin tilauksiin.
.accepts_marketing?	Boolen arvo	Palauttaa, hyväksyykö asiakas markkinoinnin.

Rivikohta

Rivikohta-olion skriptimenetelmät

Metodi	Palautustyyppi	Kuvaus
.grams	grammaa	Palauttaa rivikohdan kokonaispainon.
.line_price	Raha	Rivikohdan hinta.
.discounted?	Boolen arvo	Palauttaa, onko rivikohdan hintaa alennettu skriptillä tai manuaalisesti lisätyllä alennuksella. Alennuskoodien käyttö ei vaikuta palautusarvoon.
.properties	Hajautustaulu	Palauttaa ominaisuudet, jotka tälle rivikohdalle on määritetty.
.variant	Variant	Palauttaa rivikohdan edustaman tuoteversion.
.quantity	Kokonaisluku	Palauttaa tämän rivikohdan määrän.
.selling_plan_id	Kokonaisluku	Palauttaa rivikohdan myyntimallin tunnuksen. Tämä menetelmä on hyödyllinen, kun kaupassa myydään toistuvia tilauksia ja haluat skriptin tunnistavan, milloin tuoteversio myydään toistuvana tilauksena.

Luettelo

Luettelo-olion skriptimenetelmät

Metodi	Palautustyyppi	Kuvaus
.new	List	Luo uuden olion, joka edustaa luetteloa.
.[]	Alkio tai nil	Palauttaa alkion määritetystä indeksistä.
.&	List	Palauttaa uuden luettelon, joka sisältää molemmille luetteloille yhteiset alkiot ilman kaksoiskappaleita.
.delete_if	List	Poistaa alkioita valinnaisen koodilohkon avulla. Katso lisätietoja Rubyn delete_if-menetelmän dokumentaatiosta.
.empty?	Boolen arvo	Palauttaa arvon true, jos luettelo ei sisällä alkioita.
.first	Alkio tai nil	Palauttaa ensimmäisen alkion tai arvon nil, jos luettelo on tyhjä.
.index(*args, &block)	kokonaisluku tai nil	Palauttaa luettelon ensimmäisen alkion indeksin. Jos argumentin sijaan annetaan lohko, palautetaan sen ensimmäisen alkion indeksi, jolle lohko on tosi.
.rindex(*args, &block)	kokonaisluku tai nil	Palauttaa luettelon viimeisen alkion indeksin. Jos argumentin sijaan annetaan lohko, palautetaan sen ensimmäisen alkion indeksi, jolle lohko on tosi.
.last	Alkio tai nil	Palauttaa viimeisen alkion tai arvon nil, jos luettelo on tyhjä.
.length	kokonaisluku	Palauttaa luettelon alkioiden määrän.
.size	kokonaisluku	Alias length-menetelmälle.
.each(*args, &block)	List	Kutsuu lohkoa kerran jokaista luettelon alkiota kohti ja välittää alkion parametrina lohkolle.

Toimitusosoite

Toimitusosoite-olion skriptimenetelmät

Metodi	Palautustyyppi	Kuvaus
.name	merkkijono	Palauttaa toimitusosoitteeseen liitetyn henkilön nimen.
.address1	merkkijono	Palauttaa toimitusosoitteen katuosoiteosan.
.address2	merkkijono	Palauttaa toimitusosoitteen katuosoitteen valinnaisen lisäkentän.
.phone	merkkijono	Palauttaa toimitusosoitteen puhelinnumeron.
.city	merkkijono	Palauttaa toimitusosoitteen kaupungin.
.zip	merkkijono	Palauttaa toimitusosoitteen postinumeron.
.province	merkkijono	Palauttaa toimitusosoitteen maakunnan/osavaltion.
.province_code	merkkijono	Palauttaa toimitusosoitteen maakunnan/osavaltion lyhennetyn arvon.
.country_code	merkkijono	Palauttaa toimitusosoitteen maan lyhennetyn arvon.

Money

Money-olion skriptimenetelmät

Metodi	Palautustyyppi	Kuvaus
.derived_from_presentment(customer_cents:X)	Raha	Konvertoi summan (sentteinä) asiakkaan paikallisesta (esitys)valuutasta kauppasi valuuttaan. Metodi hyväksyy customer_cents-parametrin, joka hyväksyy luvun sentteinä. Esimerkiksi Money.derived_from_presentment(customer_cents: 500).
.new	Raha	Luo uuden objektin, joka edustaa hintaa.
.zero	Raha	Luo uuden objektin, jonka hinta on nolla.
+	Raha	Laskee yhteen kaksi Money-objektia.
-	Raha	Vähentää yhden Money-objektin toisesta.
*	Raha	Kertoo Money-objektin luvulla.

Money-esimerkkejä

Money.new(cents: 1000)

Luo Money-objektin, joka vastaa 1 000 senttiä eli 10 $.

Money.new(cents: 100) * 50

Luo Money-objektin, joka vastaa 1 $:a, ja kertoo sitten kyseisen summan 50:llä. Palauttaa Money-objektin, joka vastaa 50 $:a.

Versio

Variant-objektia käyttävät skriptimetodit

Metodi	Palautustyyppi	Kuvaus
.id	Kokonaisluku	Palauttaa version tunnuksen.
.price	Raha	Palauttaa version yksikköhinnan.
.product	Tuote	Palauttaa versioon liittyvän tuotteen.
.skus	Luettelo<merkkijono>	Palauttaa version varastoyksiköt (SKU-koodit), joita käytetään usein varaston seurantaan.
.title	Merkkijono	Palauttaa version nimen.

Tuote

Product-objektia käyttävät skriptimetodit

Metodi	Palautustyyppi	Kuvaus
.id	Kokonaisluku	Palauttaa tuotteen tunnuksen.
.gift_card?	Boolen arvo	Palauttaa tiedon siitä, onko tuote lahjakortti.
.tags	List<Tag>	Palauttaa merkkijonoluettelon, joka sisältää tälle tuotteelle asetetut tunnisteet.
.product_type	Merkkijono	Tuotteeseen liitettävä luokittelu, jota käytetään yleisesti suodattamiseen ja hakemiseen.
.vendor	Merkkijono	Palauttaa tämän tuotteen myyjän.

Kernel

Kernel on Ruby-moduuli, joka sisältyy jokaiseen luokkaan. Tämän seurauksena sen metodit ovat jokaisen objektin käytettävissä. Nämä metodit toimivat samalla tavalla kuin globaalit funktiot muissa kielissä.

Kernel-objektia käyttävät skriptimetodit

Metodi	Palautustyyppi	Kuvaus
.exit	ei mitään	Päättää nykyisen skriptin suorituksen ilman virhettä. Jos tämä suoritetaan ennen kuin mitään on määritetty Output.cart-kohteeseen, skriptillä ei ole vaikutusta. Tämä on hyödyllinen tapa poistua skripteistä esimerkiksi silloin, jos asiakas ei ole oikeutettu suorittamaan skriptiä.

Kernel-esimerkki

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

Rivikohtien metodit

Seuraavat metodit ovat käytettävissä vain rivikohtaskripteissä:

Ostoskori

Cart-objektia käyttävät skriptimetodit rivikohtaskripteissä

Metodi	Palautustyyppi	Kuvaus
.subtotal_price_was	Raha	Palauttaa ostoskorin välisumman ennen alennusten lisäämistä.
.subtotal_price_changed?	Boolen arvo	Palauttaa tiedon siitä, onko välisumma muuttunut.

Rivikohta

LineItem-objektia käyttävät skriptimetodit rivikohtaskripteissä

Metodi	Palautustyyppi	Kuvaus
.change_line_price(Money new_price, { message: merkkijono })	Raha	Muuttaa rivikohdan hinnan määritettyyn summaan. message on pakollinen. new_price-arvon on oltava nykyistä hintaa alhaisempi.
.original_line_price	Raha	Palauttaa rivikohdan alkuperäisen hinnan ennen skriptien ja alennusten soveltamista.
.line_price_was	Raha	Palauttaa rivikohdan hinnan ennen kuin nykyinen skripti sovelsi muutoksia.
.line_price_changed?	Boolen arvo	Palauttaa tiedon siitä, onko rivikohdan hinta muuttunut.
.change_properties(hajautustaulu new_properties, { message: merkkijono })	Hajautustaulu	Asettaa rivikohdalle uudet ominaisuudet. Alkuperäinen ominaisuuksien hajautustaulu tallennetaan properties_was-kohteeseen, ja metodille välitetystä ominaisuuksien hajautustaulusta tulee rivikohdan uudet ominaisuudet.
.properties_was	Hajautustaulu	Palauttaa rivikohdan alkuperäisen ominaisuuksien hajautustaulun ennen muutosten soveltamista.
.properties_changed?	Boolen arvo	Palauttaa tiedon siitä, onko rivikohdan ominaisuuksia muutettu.
.split({ take: kokonaisluku })	Rivikohta	Jakaa rivikohdan kahdeksi rivikohdaksi. take määrittää, mikä määrä poistetaan alkuperäisestä rivikohdasta uuden rivikohdan luomiseksi.

.split-esimerkki

Tämä esimerkkiskripti jakaa original_line_item-nimisen rivikohdan kahdeksi rivikohdaksi. Uuden rivikohdan määrä on 1 (määritettynä take: 1). Sitten skripti soveltaa uuteen rivikohtaan alennetun hinnan viestillä ”Kolmas hattu 5 dollarilla”.

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

Versio

Variant-objektia käyttävät skriptimetodit rivikohtaskripteissä

Metodi	Palautustyyppi	Kuvaus
.compare_at_price	Raha	Palauttaa version vertailuhinnan. Palauttaa nil, jos versiolla ei ole vertailuhintaa.

Toimitusmetodit

Seuraavat metodit ovat käytettävissä toimitusskripteissä:

Syöte

Input-objektia käyttävät skriptimetodit toimitusskripteissä

Metodi	Palautustyyppi	Kuvaus
.shipping_rates	ToimitusmaksuLuettelo	Palauttaa luettelon kaikista toimitushinnoista.

ShippingRateList

ShippingRateList-objektin komentosarjamenetelmät toimituskomentosarjoissa

Metodi	Palautustyyppi	Kuvaus
.delete_if	ToimitusmaksuLuettelo	Poista toimitushinnat valinnaisella koodilohkolla. Katso lisätietoja Rubyn delete_if-menetelmän dokumentaatiosta.
.sort!	ToimitusmaksuLuettelo	Järjestä toimitushinnat vertailuoperaattorilla tai valinnaisella koodilohkolla. Katso lisätietoja Rubyn sort!-menetelmän dokumentaatiosta.
.sort_by!	ToimitusmaksuLuettelo	Järjestä toimitushinnat valinnaisella koodilohkolla. Katso lisätietoja Rubyn sort_by!-menetelmän dokumentaatiosta.

ShippingRate

ShippingRate-objektin komentosarjamenetelmät toimituskomentosarjoissa

Metodi	Palautustyyppi	Kuvaus
.code	Merkkijono	Palauttaa toimitushinnan koodin.
.markup	Raha	Palauttaa toimitushinnan marginaalin, jos sovellettavissa.
.name	Merkkijono	Palauttaa toimitushinnan nimen. Sitä voidaan muokata change_name-menetelmällä.
.price	Raha	Palauttaa toimitushinnan.
.source	Merkkijono	Palauttaa toimitushintaan liitetyn lähteen (kuljetuspalvelun), jos se on oleellista. Sitä ei voi muokata.
.change_name(String new_name)	Merkkijono	Muuttaa toimitushinnan nimen (enintään 255 merkkiä). Lähdettä ei voi muuttaa, poistaa tai piilottaa.
.apply_discount(Money discount, { message: String })	Raha	Lisää määritetyn kiinteän summan suuruisen alennuksen. Hintaa ei voi laskea alle nollan. Viesti vaaditaan.
.phone_required?	Boolen arvo	Palauttaa arvon true, jos puhelinnumero vaaditaan toimitushinnan saamiseksi, tai arvon false, jos puhelinnumeroa ei vaadita.

Maksutavat

Seuraavia menetelmiä voi käyttää maksukomentosarjaoissa:

Syöte

Input-objektin komentosarjamenetelmät maksukomentosarjaoissa

Metodi	Palautustyyppi	Kuvaus
.payment_gateways	PaymentGatewaysList	Palauttaa luettelon kaikista kaupan maksuportaaleista.

PaymentGatewayList

PaymentGatewayList-objektin komentosarjamenetelmät maksukomentosarjaoissa

Metodi	Palautustyyppi	Kuvaus
.delete_if	PaymentGatewayList	Poista maksuportaalit valinnaisella koodilohkolla. Katso lisätietoja Rubyn delete_if-menetelmän dokumentaatiosta.
.sort!	PaymentGatewayList	Järjestä maksuportaalit vertailuoperaattorilla tai valinnaisella koodilohkolla. Katso lisätietoja Rubyn sort!-menetelmän dokumentaatiosta.
.sort_by!	PaymentGatewayList	Järjestä maksuportaalit valinnaisella koodilohkolla. Katso lisätietoja Rubyn sort_by!-menetelmän dokumentaatiosta.

PaymentGateway

Metodi	Palautustyyppi	Kuvaus
.name	Merkkijono	Palauttaa maksuportaalin nimen.
.enabled_card_brands	Luettelo<merkkijono>	Jos maksuportaali tukee luottokortteja, se palauttaa luettelon kaupan hyväksymistä luottokorttityypeistä. Jos portaali ei tue luottokortteja, se palauttaa tyhjän luettelon.
.change_name(String new_name)	Merkkijono	Muuttaa maksuportaalin nimen. Logolla varustettuja maksuportaaleja ei voi nimetä uudelleen.

Esimerkit

Seuraavassa rivikohdan komentosarjaesimerkissä tuotteen hintaa alennetaan 9 dollarilla, kun asiakas tilaa muun tuotteen kuin lahjakortin. Esimerkissä näytetään myös asiakkaan kaikilla kaupassasi tekemillään käynneillä käyttämä kokonaissumma:

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

Lue lisää

Lue lisää seuraavista aiheista:

• Rubyn perusteet
• Komentosarjojen luominen
• Komentosarjojen testaaminen ja vianetsintä
• Liquid-mallien päivittäminen komentosarjoja varten
• Shopify Scripts