Referință API pentru scripturile Shopify

Scripturile sunt scrise cu un API Ruby care vă oferă un grad mare de control și flexibilitate.

Cerință de plan

Scripturile Shopify și aplicația Script Editor sunt disponibile numai pentru magazinele din planul Shopify Plus. Aplicația Script Editor nu mai este disponibilă pentru descărcare din Shopify App Store.

La data de 30 iunie 2026, scripturile Shopify vor fi eliminate și nu vor mai funcționa. Dacă doriți asistență continuă pentru cazurile de utilizare existente ale scripturilor Shopify, atunci trebuie să treceți la înlocuitori compatibili Shopify Functions pentru scripturile dvs. de plată, expediere sau rânduri existente. Aflați mai multe despre trecerea de la scripturi Shopify la Shopify Functions.

Există diferite tipuri de scripturi. Unui script i se atribuie un tip atunci când îl creați în aplicația Script Editor, în funcție de șablonul de script cu care alegeți să începeți:

Scripturi pentru rânduri

Scripturile pentru rânduri afectează rândurile din coș și pot modifica prețurile și acorda reduceri. Aceste scripturi sunt executate atunci când se face o modificare în coș.

Scripturile pentru rânduri care reduc un abonament se aplică numai primei plăți a abonamentului. Plățile ulterioare nu sunt reduse de script.

Anumite metode pot fi utilizate numai în scripturile pentru rânduri.

Scripturi de expediere

Scripturile de expediere interacționează cu expedierea și pot modifica metodele de transport și acorda reduceri la tarifele de transport. Aceste scripturi sunt executate atunci când procesul de plată ajunge la pagina cu opțiuni de expediere.

Scripturile de expediere care reduc tariful de transport pentru un abonament se aplică numai primei plăți a abonamentului. Plățile ulterioare nu sunt reduse de script.

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

Scripturi de plată

Scripturile de plată interacționează cu plățile și pot redenumi, ascunde și reordona gateway-urile de plată. Rețineți că scripturile de plată nu interacționează cu gateway-urile de plată afișate înainte de ecranul de plată, cum ar fi Apple Pay. Aceste scripturi se execută atunci când procesul de plată ajunge la pagina de plată.

Anumite metode pot fi utilizate numai în scripturile de plată.

Metode generale

Următoarele metode pot fi utilizate în orice tip de script:

Intrare

Metode de intrare ale scriptului

Metodă	Tip returnat	Descriere
.cart	Coș	Returnează un obiect de coș mutabil.
.locale	șir	Returnează parametrii locali ai clientului. De exemplu, en, fr sau pt-BR.

Coș

Obiectul coș este disponibil numai în magazinul online. Unele plăți abandonate au acces la obiectul coș. Cu toate acestea, dacă o plată a fost închisă și apoi un client vizitează plata abandonată, acesta este trimis la pagina de plată precompletată și obiectul coș nu mai există. Acest lucru se datorează faptului că magazinul online a fost ocolit de e-mailul de plată abandonată.

Metode de script care utilizează obiectul Coș

Metodă	Tip returnat	Descriere
.customer	Client	Returnează proprietarul coșului (dacă există).
.shipping_address	Adresă de livrare	Returnează adresa de livrare a proprietarului coșului (dacă există).
.discount_code	variază	Returnează: nil dacă coșul nu are niciun cod de reducere CartDiscount::FixedAmount dacă coșul are o reducere cu sumă fixă CartDiscount::Percentage dacă coșul are o reducere procentuală CartDiscount::Shipping dacă coșul are o reducere la expediere Returnează un singur cod de reducere (consultați Limitări) discount_code este prezent dacă s-a aplicat o reducere la coș. Acest lucru nu înseamnă neapărat că prețul coșului se modifică. De exemplu, dacă o reducere se aplică la coșuri de peste 50 USD, iar un script reduce prețul coșului sub 50 USD, discount_code este încă prezent, dar prețul coșului nu se modifică. <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

Metode de script care utilizează obiectul CartDiscount::FixedAmount

Metodă	Tip returnat	Descriere
.code	Șir	Returnează codul de reducere utilizat pentru a aplica reducerea.
.amount	Money	Returnează valoarea monetară a reducerii.
.reject({ message: Șir })	nil	Respinge codul de reducere aplicat coșului. Este necesar un mesaj.
.rejected?	Boolean	Returnează dacă a fost respins codul de reducere.

CartDiscount::Percentage

Metode de script care utilizează obiectul CartDiscount::Percentage

Metodă	Tip returnat	Descriere
.code	Șir	Returnează codul de reducere utilizat pentru a aplica reducerea.
.percentage	Zecimal	Returnează valoarea procentuală a reducerii.
.reject({ message: Șir })	nil	Respinge codul de reducere aplicat coșului. Este necesar un mesaj.
.rejected?	Boolean	Returnează dacă a fost respins codul de reducere.

CartDiscount::Shipping

Metode de script care utilizează obiectul CartDiscount::Shipping

Metodă	Tip returnat	Descriere
.code	Șir	Returnează codul de reducere utilizat pentru a aplica reducerea.
.reject({ message: Șir })	nil	Respinge codul de reducere aplicat coșului. Este necesar un mesaj.
.rejected?	Boolean	Returnează dacă a fost respins codul de reducere.

Client

Metode de script care utilizează obiectul Client

Metodă	Tip returnat	Descriere
.id	Număr întreg	Returnează ID-ul clientului.
.email	Șir	Returnează adresa de e-mail a clientului.
.tags	Listă<Etichetă>	Returnează o listă de șiruri care reprezintă orice etichete setate pentru un client.
.orders_count	Număr întreg	Returnează numărul total de comenzi pe care le-a plasat un client.
.total_spent	Money	Returnează suma totală pe care clientul a cheltuit-o pentru toate comenzile.
.accepts_marketing?	Boolean	Returnează dacă clientul acceptă marketingul.

Rând

Metode de script care utilizează obiectul Rând

Metodă	Tip returnat	Descriere
.grams	grame	Returnează greutatea totală a rândului.
.line_price	Money	Prețul rândului.
.discounted?	Boolean	Returnează dacă prețul unui rând a fost redus de un script sau de o reducere aplicată manual. Utilizarea codurilor de reducere nu afectează valoarea returnată.
.properties	hash	Returnează proprietățile care au fost specificate pentru acest rând.
.variant	Variantă	Returnează varianta de produs specifică reprezentată de rând.
.quantity	Număr întreg	Returnează cantitatea acestui rând.
.selling_plan_id	Număr întreg	Returnează ID-ul planului de vânzări pentru rând. Această metodă este utilă atunci când magazinul vinde abonamente și doriți ca scriptul să detecteze când o variantă de produs este vândută ca abonament.

Listă

Metode de script care utilizează obiectul Listă

Metodă	Tip returnat	Descriere
.new	Listă	Creează un obiect nou pentru a reprezenta o listă.
.[]	Element sau nil	Returnează elementul de la indexul specificat.
.&	Listă	Returnează o listă nouă care conține elementele comune celor două liste, fără duplicate.
.delete_if	Listă	Șterge elemente folosind un bloc de cod opțional. Consultați documentația pentru metoda delete_if a limbajului Ruby.
.empty?	Boolean	Returnează true dacă lista nu conține niciun element.
.first	Element sau nil	Returnează primul element sau nil dacă lista este goală.
.index(*args, &block)	int sau nil	Returnează indexul primului element al listei. Dacă se oferă un bloc în locul unui argument, returnează indexul primului element pentru care blocul este adevărat.
.rindex(*args, &block)	int sau nil	Returnează indexul ultimului element al listei. Dacă se oferă un bloc în locul unui argument, returnează indexul primului element pentru care blocul este adevărat.
.last	Element sau nil	Returnează ultimul element sau nil dacă lista este goală.
.length	int	Returnează numărul de elemente din listă.
.size	int	Alias pentru length.
.each(*args, &block)	Listă	Apelează un bloc o dată pentru fiecare element din listă, transmițând elementul ca parametru la bloc.

Adresă de livrare

Metode de script care utilizează obiectul Adresă de livrare

Metodă	Tip returnat	Descriere
.name	șir	Returnează numele persoanei asociate cu adresa de livrare.
.address1	șir	Returnează partea cu adresa stradală a adresei de livrare.
.address2	șir	Returnează câmpul suplimentar opțional al părții cu adresa stradală a adresei de livrare.
.phone	șir	Returnează numărul de telefon al adresei de livrare.
.city	șir	Returnează orașul adresei de livrare.
.zip	șir	Returnează codul poștal al adresei de livrare.
.province	șir	Returnează provincia/statul adresei de livrare.
.province_code	șir	Returnează valoarea abreviată a provinciei/statului adresei de livrare.
.country_code	șir	Returnează valoarea abreviată a țării adresei de livrare.

Money

Metode de script care utilizează obiectul Money

Metodă	Tip returnat	Descriere
.derived_from_presentment(customer_cents:X)	Money	Convertește o sumă (în cenți) din moneda locală a clientului (prezentată) în moneda magazinului dvs. Această metodă acceptă parametrul customer_cents, care acceptă un număr în cenți. De exemplu, Money.derived_from_presentment(customer_cents: 500).
.new	Money	Creează un obiect nou pentru a reprezenta un preț.
.zero	Money	Creează un obiect nou cu un preț de zero.
+	Money	Adună două obiecte Money.
-	Money	Scade un obiect Money dintr-un altul.
*	Money	Înmulțește un obiect Money cu un număr.

Exemple Money

Money.new(cents: 1000)

Creează un obiect Money reprezentând 1000 de cenți, sau 10 $.

Money.new(cents: 100) * 50

Creează un obiect Money reprezentând 1 $, apoi înmulțește suma respectivă cu 50. Returnează un obiect Money reprezentând 50 $.

Variantă

Metode de script care utilizează obiectul Variantă

Metodă	Tip returnat	Descriere
.id	Număr întreg	Returnează numărul ID al variantei.
.price	Money	Returnează prețul la bucată al variantei.
.product	Produs	Returnează produsul asociat al variantei.
.skus	Listă<Șir>	Returnează unitățile de gestiune a stocurilor (numere de inventar) ale variantei, care sunt adesea utilizate pentru urmărirea inventarului.
.title	Șir	Returnează titlul variantei.

Produs

Metode de script care utilizează obiectul Produs

Metodă	Tip returnat	Descriere
.id	Număr întreg	Returnează numărul ID al produsului.
.gift_card?	Boolean	Returnează dacă produsul este un card cadou.
.tags	Listă<Etichetă>	Returnează o listă de șiruri care reprezintă etichetele setate pentru acest produs.
.product_type	Șir	O clasificare cu care un produs poate fi etichetat, utilizată frecvent pentru filtrare și căutare.
.vendor	Șir	Returnează vânzătorul acestui produs.

Kernel

Kernel este un modul Ruby care este inclus în fiecare clasă. Ca urmare, metodele sale sunt disponibile pentru fiecare obiect. Aceste metode acționează în același mod ca funcțiile globale din alte limbi.

Metode de script care utilizează obiectul Kernel

Metodă	Tip returnat	Descriere
.exit	nimic	Încheie execuția scriptului curent fără erori. Dacă se execută înainte ca ceva să fie atribuit la Output.cart, scriptul nu are niciun efect. Aceasta este o modalitate utilă de a ieși din scripturi, de exemplu, dacă clientul nu este eligibil pentru rularea scriptului.

Exemplu Kernel

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

Metode pentru rânduri

Următoarele metode se pot utiliza numai în scripturi pentru rânduri:

Coș

Metode de script care utilizează obiectul Coș în scripturile pentru rânduri

Metodă	Tip returnat	Descriere
.subtotal_price_was	Money	Returnează subtotalul coșului înainte de aplicarea oricăror reduceri.
.subtotal_price_changed?	Boolean	Returnează dacă subtotalul s-a modificat.

Rând

Metode de script care utilizează obiectul Rând în scripturile pentru rânduri

Metodă	Tip returnat	Descriere
.change_line_price(Money new_price, { message: Șir })	Money	Modifică prețul rândului la suma specificată. Este necesar un mesaj. new_price trebuie să fie mai mic decât prețul curent.
.original_line_price	Money	Returnează prețul inițial al rândului, înainte de aplicarea scripturilor și a reducerilor.
.line_price_was	Money	Returnează prețul rândului înainte de aplicarea modificărilor de către scriptul curent.
.line_price_changed?	Boolean	Returnează dacă prețul rândului s-a modificat.
.change_properties(hash new_properties, { message: Șir })	hash	Setează proprietăți noi pentru un rând. Hash-ul de proprietăți inițial este stocat în properties_was, iar hash-ul de proprietăți care este transmis metodei devine noile proprietăți pentru rând.
.properties_was	hash	Returnează hash-ul de proprietăți inițial al rândului înainte de aplicarea oricăror modificări.
.properties_changed?	Boolean	Returnează dacă proprietățile rândului au fost modificate.
.split({ take: Număr întreg })	Rând	Împarte un rând în două rânduri. take specifică ce cantitate trebuie eliminată din rândul inițial pentru a crea noul rând.

Exemplu .split

Acest exemplu de script împarte un rând numit original_line_item în două rânduri. Noul rând are o cantitate de 1 (specificată prin take: 1). Scriptul aplică apoi un preț redus noului rând, cu mesajul „A treia pălărie pentru 5 dolari”.

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ă

Metode de script care utilizează obiectul Variantă în scripturile pentru rânduri

Metodă	Tip returnat	Descriere
.compare_at_price	Money	Returnează prețul de comparație al variantei. Returnează nil dacă varianta nu are un preț de comparație.

Metode de transport

Următoarele metode se pot utiliza în scripturi de expediere:

Intrare

Metode de script care utilizează obiectul Input în scripturile de expediere

Metodă	Tip returnat	Descriere
.shipping_rates	ShippingRateList	Returnează o listă cu toate tarifele de transport.

ShippingRateList

Metode de script care utilizează obiectul ShippingRateList în scripturile de expediere

Metodă	Tip returnat	Descriere
.delete_if	ShippingRateList	Șterge tarifele de transport folosind un bloc de cod opțional. Consultați documentația pentru metoda delete_if a Ruby.
.sort!	ShippingRateList	Sortează tarifele de transport folosind operatorul de comparație sau un bloc de cod opțional. Consultați documentația pentru metoda sort! a Ruby.
.sort_by!	ShippingRateList	Sortează tarifele de transport folosind un bloc de cod opțional. Consultați documentația pentru metoda sort_by! a Ruby.

ShippingRate

Metode de script care utilizează obiectul ShippingRate în scripturile de expediere

Metodă	Tip returnat	Descriere
.code	Șir	Returnează codul tarifului de transport.
.markup	Money	Returnează adaosul comercial pentru un tarif de transport, dacă este cazul.
.name	Șir	Returnează numele tarifului de transport. Acesta poate fi modificat folosind metoda change_name.
.price	Money	Returnează prețul tarifului de transport.
.source	Șir	Returnează sursa (transportatorul) asociată tarifului de transport, dacă este relevant. Aceasta nu poate fi modificată.
.change_name(Șir new_name)	Șir	Modifică numele (maximum 255 de caractere) al tarifului de transport. Nu este posibilă modificarea, ștergerea sau ascunderea sursei.
.apply_discount(Money discount, { message: String })	Money	Aplică o reducere cu suma fixă specificată. Prețul nu poate fi redus sub 0. Este necesar un mesaj.
.phone_required?	Boolean	Returnează true dacă este necesar un număr de telefon pentru a obține tariful de transport sau false dacă nu este necesar un număr de telefon.

Metode de plată

Următoarele metode pot fi utilizate în scripturile de plată:

Intrare

Metode de script care utilizează obiectul Input în scripturile de plată

Metodă	Tip returnat	Descriere
.payment_gateways	PaymentGatewaysList	Returnează o listă cu toate gateway-urile de plată din magazin.

PaymentGatewayList

Metode de script care utilizează obiectul PaymentGatewayList în scripturile de plată

Metodă	Tip returnat	Descriere
.delete_if	PaymentGatewayList	Șterge gateway-uri de plată folosind un bloc de cod opțional. Consultați documentația pentru metoda delete_if a Ruby.
.sort!	PaymentGatewayList	Sortează gateway-urile de plată folosind operatorul de comparație sau un bloc de cod opțional. Consultați documentația pentru metoda sort! a Ruby.
.sort_by!	PaymentGatewayList	Sortează gateway-urile de plată folosind un bloc de cod opțional. Consultați documentația pentru metoda sort_by! a Ruby.

PaymentGateway

Metodă	Tip returnat	Descriere
.name	Șir	Returnează numele gateway-ului de plată.
.enabled_card_brands	Listă<Șir>	Dacă gateway-ul de plată acceptă carduri de credit, returnează o listă a tipurilor de carduri de credit pe care le acceptă magazinul. Dacă gateway-ul nu acceptă carduri de credit, returnează o listă goală.
.change_name(Șir new_name)	Șir	Modifică numele gateway-ului de plată. Gateway-urile de plată cu sigle nu pot fi redenumite.

Exemple

În următorul exemplu de script de rând, atunci când un client comandă un produs care nu este un card cadou, prețul produsului este redus cu 9 $. De asemenea, este afișată suma totală pe care clientul a cheltuit-o de-a lungul tuturor vizitelor în magazinul dvs.:

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

Aflați mai multe

Aflați mai multe despre:

• Noțiunile de bază ale limbajului Ruby
• Crearea de scripturi
• Testarea și depanarea scripturilor dvs.
• Actualizarea șabloanelor Liquid pentru scripturi
• Scripturi Shopify