Riferimento API Shopify Scripts

Questa pagina è stata stampata il Apr 23, 2024. 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 metodi possono essere utilizzati solo negli script di voci dell'ordine.

Script di spedizione

Gli script di spedizione interagiscono con la spedizione: 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 metodi possono essere utilizzati solo negli script di spedizione.

Script di pagamento

Gli script di pagamento interagiscono con i pagamenti e possono rinominare, nascondere e riordinare i 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 metodi possono 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 , fr o pt-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 di discount_code.
.line_items List<LineItem> Restituisce un elenco delle voci dell'ordine presenti nel carrello.
.presentment_currency List<String> Restituisce la valuta locale (di presentazione) del cliente (nel formato ISO 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 un messaggio.
.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 un messaggio.
.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 un messaggio.
.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<Tag> 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

<tdgrammi
Metodi script tramite l'oggetto LineItem
Metodo Tipo restituito Descrizione
.grams Restituisce il peso totale della voce dell'ordine.
.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 viene venduta in abbonamento.

List

Metodi script tramite l'oggetto List
Metodo Tipo restituito Descrizione
.new List Crea un nuovo oggetto per rappresentare un elenco.
.[] Element o nil

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 il metodo delete_if di Ruby.
.empty? Boolean

Restituisce true se l'elenco non contiene elementi.
.first Element o nil

Restituisce il primo elemento o nil se 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 Element o nil

Restituisce l'ultimo elemento o nil se 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 parametro customer_cents, che specifica un 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 oggetti Money.
- Money Sottrae un oggetto Money da un altro.
* Money Moltiplica un oggetto Money per un numero.

Esempi di Money

Money.new(cents: 1000)

Crea un oggetto Money che rappresenta 1000 centesimi o € 10.

Money.new(cents: 100) * 50

Crea un oggetto Money che rappresenta € 1, quindi moltiplica tale importo per 50. Restituisce un oggetto Money che rappresenta € 50.

Variant

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<String> 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<Tag> 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 a Output.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.customer
if customer && customer.email.end_with?("@mycompany.com")
  # Employees are not eligible for this promotion.
  exit
end

Metodi per le voci

I seguenti metodi sono utilizzabili solo negli script 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(Money new_price, { message: String }) Money Modifica il prezzo della voce nell'importo specificato. È richiesto un messaggio. new_price deve 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(hash new_properties, { message: String }) hash Imposta nuove proprietà per un articolo. L'hash delle proprietà originali viene memorizzato in properties_was e 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. take specifica 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 chiamata original_line_item in due voci distinte. La nuova voce ha 1 come quantità (specificata da take: 1). Lo script applica quindi un prezzo scontato alla nuova voce con il messaggio "Third hat for 5 dollars" (Terzo cappello a 5 dollari).

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

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. Restituisce nil se la variante non ha un prezzo di confronto.

Modalità di spedizione

I seguenti metodi sono utilizzabili negli script 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 script 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 metodo delete_if di Ruby.
.sort! ShippingRateList Ordina le tariffe di spedizione utilizzando l'operatore di confronto o un blocco di codice opzionale. Consulta la documentazione per il metodo sort! di Ruby.
.sort_by! ShippingRateList Ordina le tariffe di spedizione utilizzando un blocco di codice opzionale. Consulta la documentazione per il metodo sort_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 metodo change_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(String new_name) String Modifica il nome (massimo 255 caratteri) della tariffa di spedizione. Non è possibile modificare, eliminare o nascondere l'origine.
.apply_discount(Money discount, { 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 Restituisce true se per ottenere la tariffa di spedizione è richiesto un numero di telefono oppure false se non è richiesto.

Metodi di pagamento

I seguenti metodi sono utilizzabili negli script 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 metodo delete_if di Ruby.
.sort! PaymentGatewayList Ordina i gateway di pagamenti utilizzando l'operatore di confronto o un blocco di codice opzionale. Consulta la documentazione per il metodo sort! di Ruby.
.sort_by! PaymentGatewayList Ordina i gateway di pagamenti utilizzando un blocco di codice opzionale. Consulta la documentazione per il metodo sort_by! di Ruby.

PaymentGateway

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

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(String new_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