Riferimento API Shopify Scripts

Questa pagina è stata stampata il Oct 29, 2023. Per la versione aggiornata, visita https://help.shopify.com/it/manual/checkout-settings/script-editor/shopify-scripts.

Gli script vengono creati con un'API di Ruby che assicura un elevato livello di controllo e flessibilità

Esistono vari tipi di script. Quando crei uno script nell'app Script Editor, allo script viene assegnato un tipo in base al modello che hai utilizzato come base:

Script di voci dell'ordine

Gli script di voci dell'ordine influiscono sulle voci presenti nel carrello, possono modificare i prezzi e assegnare sconti. Tali script vengono eseguiti a ogni modifica del carrello.

Gli script di articolo che assegnano uno sconto all'abbonamento si applicano solo al primo pagamento; quelli successivi non saranno scontati dallo script.

Alcuni metodipossono essere utilizzati solo negli script di voci dell'ordine.

Script di spedizione

Gli script di spedizione interagiscono con laspedizione: possono modificare le modalità di spedizione e assegnare sconti alle relative tariffe. Questi script vengono eseguiti ogni volta che, durante il check-out, viene raggiunta la pagina delle opzioni di spedizione.

Gli script di spedizione che scontano la tariffa di spedizione di un abbonamento si applicano solo al primo pagamento. I pagamenti successivi non verranno scontati dallo script.

Alcuni metodipossono essere utilizzati solo negli script di spedizione.

Script di pagamento

Gli script di pagamento interagiscono con ipagamentie possono rinominare nascondere e riordinare我gateway di pagamento. È importante sottolineare che gli script di pagamento non interagiscono con i gateway di pagamento mostrati prima della schermata di check-out, come Apple Pay. Questi script vengono eseguiti quando la procedura di check-out raggiunge la pagina di pagamento.

Alcuni metodipossono essere utilizzati solo negli script di pagamento.

Su questa pagina

Metodi generali

I seguenti metodi sono utilizzabili in qualsiasi tipo di script:

Input

Metodi di input per script
Metodo Tipo restituito Descrizione
.cart Carrello Restituisce un oggetto carrello variabile.
. locale stringa Restituisce l'impostazione locale del cliente. Ad esempio,en,fropt-BR.

Carrello

L'oggetto carrello è disponibile solo nel negozio online. Alcuni check-out abbandonati hanno accesso all'oggetto carrello. Tuttavia, se un check-out è stato chiuso e il cliente visita il check-out abbandonato, viene indirizzato al check-out precompilato e l'oggetto carrello non esisterà più. Questo si verifica perché la vetrina virtuale è stata bypassata dall'email per il check-out abbandonato.

Metodi script tramite l'oggetto carrello
Metodo Tipo restituito Descrizione
.customer Cliente Restituisce il proprietario del carrello (se presente).
.shipping_address ShippingAddress Restituisce l'indirizzo di spedizione del proprietario del carrello (se presente).
.discount_code varia Restituisce:

discount_codeè presente se al carrello è stato applicato uno sconto. Questo non comporta necessariamente una modifica del prezzo del carrello. Ad esempio, se uno sconto si applica ai carrelli superiori a € 50 e uno script riduce il prezzo del carrello a meno di € 50,discount_codeè presente ma il prezzo del carrello non cambia.

Visualizza un esempio didiscount_code.
.line_items List Restituisce un elenco delle voci dell'ordine presenti nel carrello.
.presentment_currency List Restituisce la valuta locale (di presentazione) del cliente (nel formatoISO 4217). Ad esempio, USD.
.subtotal_price Money Restituisce il subtotale del prezzo del carrello dopo l'applicazione degli sconti per voci dell'ordine, ma prima dell'applicazione dei codici sconto.
.total_weight grammi Restituisce il peso totale di tutte le voci dell'ordine presenti nel carrello.

CartDiscount::FixedAmount

Metodi script tramite l'oggetto CartDiscount:: FixedAmount
Metodo Tipo restituito Descrizione
.code String Restituisce il codice sconto utilizzato per applicare lo sconto.
.amount Money Restituisce l'importo in denaro dello sconto.
.reject({ message: String }) nil Rifiuta il codice sconto applicato al carrello. È richiesto unmessaggio.
.rejected? Boolean Indica se il codice sconto è stato rifiutato.

CartDiscount::Percentage

Metodi script tramite l'oggetto CartDiscount::Percentage
Metodo Tipo restituito Descrizione
.code String Restituisce il codice sconto utilizzato per applicare lo sconto.
.percentage Decimale Restituisce l'importo percentuale dello sconto.
.reject({ message: String }) nil Rifiuta il codice sconto applicato al carrello. È richiesto unmessaggio.
.rejected? Boolean Indica se il codice sconto è stato rifiutato.

CartDiscount::Shipping

Metodi script tramite l'oggetto CartDiscount::Shipping
Metodo Tipo restituito Descrizione
.code String Restituisce il codice sconto utilizzato per applicare lo sconto.
.reject({ message: String }) nil Rifiuta il codice sconto applicato al carrello. È richiesto unmessaggio.
.rejected? Boolean Indica se il codice sconto è stato rifiutato.

Cliente

Metodi script tramite l'oggetto Customer
Metodo Tipo restituito Descrizione
.id Integer Restituisce il numero identificativo del cliente.
.email String Restituisce l'indirizzo email del cliente.
.tags List Restituisce un elenco di stringhe che rappresentano qualsiasi set di tag relativo a un cliente.
.orders_count Integer Restituisce il numero totale di ordini effettuati da un cliente.
.total_spent Money Restituisce l'importo totale speso dal cliente per tutti gli ordini.
.accepts_marketing? Boolean Indica se il cliente accetta comunicazioni di marketing.

LineItem

grammi Restituisce il peso totale della voce dell'ordine.
Metodi script tramite l'oggetto LineItem
Metodo Tipo restituito Descrizione
.grams
.line_price Money Il prezzo dell’articolo.
.discounted? Boolean Indica se il prezzo di una voce è stato scontato da uno script o da uno sconto applicato manualmente. L'utilizzo dei codici sconto non influisce sul valore di ritorno.
.properties hash Restituisce le proprietà che sono state specificate per questo articolo.
.variant Variante Restituisce la variante di prodotto specifica rappresentata dalla voce dell'ordine.
.quantity Integer Restituisce la quantità di questo articolo.
.selling_plan_id Integer Restituisce l'ID del piano di vendita della voce. Questo metodo è utile quando il negozio vende abbonamenti e desideri che lo script rilevi quando una variante di prodotto vienevenduta in abbonamento.

List

Metodi script tramite l'oggetto List
Metodo Tipo restituito Descrizione
.new List Crea un nuovo oggetto per rappresentare un elenco.
.[] 阿零元素

Restituisce l'elemento nell'indice specificato.
.& List

Restituisce un nuovo elenco contenente elementi comuni ai due elenchi, senza duplicati.
.delete_if List Elimina gli elementi utilizzando un blocco di codice opzionale. Consulta la documentazione per ilmetododelete_ifdi Ruby.
.empty? Boolean

Restituiscetruese l'elenco non contiene elementi.
.first 阿零元素

Restituisce il primo elemento onilse l'elenco è vuoto.
.index(*args, &block) int o nil

Restituisce l'indice del primo elemento dell'elenco. Se invece di un argomento viene fornito un blocco, restituisce l'indice del primo elemento per il quale il blocco è true.
.rindex(*args, &block) int o nil

Restituisce l'indice dell'ultimo elemento dell'elenco. Se invece di un argomento viene fornito un blocco, restituisce l'indice del primo elemento per il quale il blocco è true.
.last 阿零元素

Restituisce l'ultimo elemento onilse l'elenco è vuoto.
.length int

Restituisce il numero di elementi presenti nell'elenco.
.size int

Alias per length (lunghezza).
.each(*args, &block) List

Chiama un blocco una volta per ogni elemento dell'elenco, passando l'elemento al blocco come parametro.

ShippingAddress

Metodi script tramite l'oggetto ShippingAddress
Metodo Tipo restituito Descrizione
.name stringa Restituisce il nome della persona associata all'indirizzo di spedizione.
.address1 stringa Restituisce la parte dell'indirizzo di spedizione relativa all'indirizzo stradale.
.address2 stringa Restituisce il campo aggiuntivo facoltativo della porzione dell'indirizzo di spedizione relativa all'indirizzo stradale.
.phone stringa Restituisce il numero di telefono associato all'indirizzo di spedizione.
.city stringa Restituisce la città indicata nell'indirizzo di spedizione.
.zip stringa Restituisce il codice postale indicato nell'indirizzo di spedizione.
.province stringa Restituisce la provincia/lo stato dell'indirizzo di spedizione.
.province_code stringa Restituisce il valore abbreviato della provincia/stato dell'indirizzo di spedizione.
.country_code stringa Restituisce il valore abbreviato del paese dell'indirizzo di spedizione.

Money

Metodi script tramite l'oggetto Money
Metodo Tipo restituito Descrizione
.derived_from_presentment (customer_cents:X) Money Converte un importo (in centesimi) dalla valuta locale (di presentazione) del cliente alla valuta del negozio. Questo metodo accetta il parametrocustomer_cents切需要的联合国numero in centesimi. Ad esempio,Money.derived_from_presentment (customer_cents: 500).
.new Money Crea un nuovo oggetto per rappresentare un prezzo.
.zero Money

Crea un nuovo oggetto con prezzo zero.
+ Money Aggiunge due oggettiMoney.
- Money Sottrae un oggettoMoneyda un altro.
* Money Moltiplica un oggettoMoneyper un numero.

Esempi di Money

Money.new(cents:1000)

Crea un oggettoMoneyche rappresenta 1000 centesimi o € 10.

Money.new(cents:100)*50

Crea un oggettoMoneyche rappresenta € 1, quindi moltiplica tale importo per 50. Restituisce un oggettoMoneyche rappresenta € 50.

Variante

Metodi script tramite l'oggetto Variant
Metodo Tipo restituito Descrizione
.id Integer Restituisce il numero identificativo della variante.
.price Money Restituisce il prezzo unitario della variante.
.product Prodotto Restituisce il prodotto associato della variante.
.skus List Restituisce le SKU (Stock Keeping Unit) della variante, spesso utilizzate per monitorare le scorte.
.title String Restituisce il titolo della variante.

Prodotto

Metodi script tramite l'oggetto Product
Metodo Tipo restituito Descrizione
.id Integer Restituisce il numero identificativo del prodotto.
.gift_card? Boolean Indica se il prodotto è un buono regalo.
.tags List Restituisce un elenco di stringhe che rappresentano i tag impostati per questo prodotto.
.product_type String Una suddivisione in categorie con cui è possibile taggare un prodotto, comunemente utilizzata per filtrare ed eseguire ricerche.
.vendor String Restituisce il fornitore di questo prodotto.

Kernel

Kernelè un modulo Ruby incluso in ogni classe. Di conseguenza, i suoi metodi sono disponibili per ogni oggetto. Tali metodi si comportano come le funzioni globali agiscono in altre lingue.

Metodi script tramite l'oggetto Kernel
Metodo Tipo restituito Descrizione
.exit nessuno Termina l'esecuzione dello script corrente senza errori. Se viene eseguito prima che un elemento venga assegnato aOutput.cart, lo script non ha alcun effetto. Si tratta di un metodo utile per uscire dagli script, ad esempio, se il cliente non è idoneo per l'esecuzione dello script stesso.

Esempio di kernel

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

Metodi per le voci

I seguenti metodi sono utilizzabili solo negliscript di voci dell'ordine:

Carrello

Metodi script tramite l'oggetto Cart negli script delle voci dell'ordine
Metodo Tipo restituito Descrizione
.subtotal_price_was Money Restituisce il subtotale del prezzo del carrello prima dell'applicazione di qualsiasi sconto.
.subtotal_price_changed? Boolean Indica se il subtotale del prezzo è cambiato.

LineItem

Metodi script tramite l'oggetto LineItem negli script delle voci dell'ordine
Metodo Tipo restituito Descrizione
.change_line_price(Moneynew_price, { message:String}) Money Modifica il prezzo della voce nell'importo specificato. È richiesto unmessaggio.new_pricedeve essere inferiore al prezzo corrente.
.original_line_price Money Restituisce il prezzo originale della voce dell'ordine prima dell'applicazione di script e sconti.
.line_price_was Money Restituisce il prezzo della voce dell'ordine prima dell'applicazione delle modifiche apportate dallo script corrente.
.line_price_changed? Boolean Indica se il prezzo dell'articolo è cambiato.
.change_properties(hashnew_properties, { message:String}) hash Imposta nuove proprietà per un articolo. L'hash delle proprietà originali viene memorizzato inproperties_wase l'hash delle proprietà che viene passato al metodo si trasforma nelle nuove proprietà della voce.
.properties_was hash Restituisce l'hash delle proprietà originali della voce dell'ordine prima dell'applicazione delle modifiche.
.properties_changed? Boolean Indica se le proprietà dell'articolo sono cambiate.
.split({ take:Integer}) LineItem Suddivide una voce dell'ordine in due voci distinte.takespecifica la quantità da rimuovere dalla voce dell'ordine originale per creare una nuova voce.

Esempio .split

Questo script di esempio suddivide una voce dell'ordine chiamataoriginal_line_itemin due voci distinte. La nuova voce ha 1 come quantità (specificata datake: 1). Lo script applica quindi un prezzo scontato alla nuova voce con il messaggio "Third hat for 5 dollars" (Terzo cappello a 5 dollari).

iforiginal_line_item.quantity>=3new_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_itemend

Variante

Metodi script tramite l'oggetto Variant negli script delle voci dell'ordine
Metodo Tipo restituito Descrizione
.compare_at_price Money Restituisce il prezzo di confronto della variante. Restituiscenilse la variante non ha un prezzo di confronto.

Modalità di spedizione

I seguenti metodi sono utilizzabili negliscript di spedizione:

Input

Metodi script tramite l'oggetto Input negli script di spedizione
Metodo Tipo restituito Descrizione
.shipping_rates ShippingRateList Restituisce un elenco di tutte le tariffe di spedizione.

ShippingRateList

Metodi脚本tramite l 'oggetto ShippingRateList negli script di spedizione
Metodo Tipo restituito Descrizione
.delete_if ShippingRateList Elimina le tariffe di spedizione utilizzando un blocco di codice opzionale. Consulta la documentazione per il metododelete_ifdi Ruby.
.sort! ShippingRateList Ordina le tariffe di spedizione utilizzando l'operatore di confronto o un blocco di codice opzionale. Consulta la documentazione per il metodosort!di Ruby.
.sort_by! ShippingRateList Ordina le tariffe di spedizione utilizzando联合国车辆cco di codice opzionale. Consulta la documentazione per il metodosort_by!di Ruby.

ShippingRate

Metodi script tramite l'oggetto ShippingRate negli script di spedizione
Metodo Tipo restituito Descrizione
.code String Restituisce il codice della tariffa di spedizione.
.markup Money Restituisce il markup per una tariffa di spedizione, se applicabile.
.name String Restituisce il nome della tariffa di spedizione. Può essere modificato utilizzando il metodochange_name.
.price Money Restituisce il prezzo della tariffa di spedizione.
.source String Restituisce l'origine (il corriere) associata alla tariffa di spedizione, se pertinente. Non può essere modificato.
.change_name(Stringnew_name) String Modifica il nome (massimo 255 caratteri) della tariffa di spedizione. Non è possibile modificare, eliminare o nascondere l'origine.
.apply_discount(Moneydiscount, { message: String }) Money Applica uno sconto dell'importo fisso specificato. Il prezzo non può essere ridotto al di sotto dello 0. È richiesto un messaggio.
.phone_required? Boolean Restituiscetruese per ottenere la tariffa di spedizione è richiesto un numero di telefono oppurefalsese non è richiesto.

Metodi di pagamento

I seguenti metodi sono utilizzabili negliscript di pagamento:

Input

Metodi script tramite l'oggetto Input negli script di pagamento
Metodo Tipo restituito Descrizione
.payment_gateways PaymentGatewaysList Restituisce un elenco di tutti i gateway di pagamento del negozio.

PaymentGatewayList

Metodi script tramite l'oggetto PaymentGatewayList negli script di pagamento
Metodo Tipo restituito Descrizione
.delete_if PaymentGatewayList Elimina i gateway di pagamento utilizzando un blocco di codice opzionale. Consulta la documentazione per il metododelete_ifdi Ruby.
.sort! PaymentGatewayList Ordina i gateway di pagamenti utilizzando l'operatore di confronto o un blocco di codice opzionale. Consulta la documentazione per il metodosort!di Ruby.
.sort_by! PaymentGatewayList Ordina i gateway di pagamenti utilizzando un blocco di codice opzionale. Consulta la documentazione per il metodosort_by!di Ruby.

PaymentGateway

Metodo Tipo restituito Descrizione
.name String Restituisce il nome del gateway di pagamento.
.enabled_card_brands List

Se il gateway di pagamento supporta le carte di credito, restituisce un elenco dei tipi di carte di credito accettati dal negozio. Se il gateway non supporta le carte di credito, restituisce un elenco vuoto.
.change_name(Stringnew_name) String Modifica il nome del canale di pagamento. I canali di pagamento con loghi non possono essere rinominati.

Esempi

Nel seguente esempio di script di voci dell'ordine, quando un cliente ordina un prodotto diverso da un buono regalo, il prezzo del prodotto viene ridotto di € 9. Viene inoltre visualizzato l'importo totale speso dal cliente tenendo in considerazione tutte le visite effettuate al tuo negozio:

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

Maggiori informazioni

Maggiori informazioni su:

Sei pronto per iniziare a vendere con Shopify?

Provalo, è gratis