Riferimento API degli script Shopify

Gli script sono scritti con un’API Ruby che offre un elevato livello di controllo e flessibilità.

Requisiti del piano

Gli script Shopify e l'app Script Editor sono disponibili solo per i negozi con il piano Shopify Plus. L'app Script Editor non è più disponibile per il download dallo Shopify App Store.

Il 30 giugno 2026 gli script Shopify verranno rimossi e non funzioneranno più. Se desideri un supporto continuo per i tuoi attuali casi d'uso degli script Shopify, devi passare a soluzioni Shopify Functions compatibili in sostituzione degli script di pagamento, spedizione o voce esistenti. Scopri di più sul passaggio dagli script Shopify a Shopify Functions.

Esistono diversi tipi di script. A uno script viene assegnato un tipo quando lo crei nell'app Script Editor, in base al modello di script che scegli per iniziare:

Script di voci

Gli script di voci intervengono sulle voci nel carrello e possono modificare i prezzi e concedere sconti. Questi script vengono eseguiti quando viene apportata una modifica al carrello.

Gli script di voci che scontano un abbonamento si applicano solo al primo pagamento dell'abbonamento. I pagamenti successivi non vengono scontati dallo script.

Alcuni metodi possono essere utilizzati solo negli script di voci.

Script di spedizione

Gli script di spedizione interagiscono con la spedizione e possono modificare i metodi di spedizione e concedere sconti sulle tariffe di spedizione. Questi script vengono eseguiti quando si accede alla pagina delle opzioni di spedizione durante il check-out.

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

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

Script di pagamento

Gli script di pagamento interagiscono con i pagamenti e possono rinominare, nascondere e riordinare i canali di pagamento. Tieni presente che gli script di pagamento non interagiscono con i canali di pagamento mostrati prima della schermata di check-out, come Apple Pay. Questi script vengono eseguiti quando si accede alla pagina di pagamento durante il check-out.

Alcuni metodi possono essere utilizzati solo negli script di pagamento.

Metodi generali

I metodi seguenti sono utilizzabili in qualsiasi tipo di script:

Input

Metodi di input degli script

Metodo	Tipo restituito	Descrizione
.cart	Cart	Restituisce un oggetto carrello modificabile.
.locale	string	Restituisce le impostazioni locali 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 un cliente visita il check-out abbandonato, viene indirizzato al check-out precompilato e l'oggetto carrello non esiste più. Questo accade perché la vetrina virtuale è stata bypassata dall'email per check-out abbandonato.

Metodi di script che utilizzano l'oggetto Cart

Metodo	Tipo restituito	Descrizione
.customer	Customer	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: nil se il carrello non ha un codice sconto CartDiscount::FixedAmount se il carrello ha uno sconto di importo fisso CartDiscount::Percentage se il carrello ha uno sconto percentuale CartDiscount::Shipping se il carrello ha uno sconto sulla spedizione Restituisce un singolo codice sconto (vedi Limitazioni) discount_code è presente se al carrello è stato applicato uno sconto. Ciò non significa necessariamente che il prezzo del carrello cambi. Ad esempio, se uno sconto si applica a carrelli di valore superiore a 50 $, e uno script riduce il prezzo del carrello al di sotto di 50 $, discount_code è ancora presente ma il prezzo del carrello non cambia. <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

Metodi di script che utilizzano l'oggetto CartDiscount::FixedAmount

Metodo	Tipo restituito	Descrizione
.code	String	Restituisce il codice sconto utilizzato per applicare lo sconto.
.amount	Money	Restituisce l'importo monetario dello sconto.
.reject({ message: String })	nil	Rifiuta il codice sconto applicato al carrello. È richiesto un message.
.rejected?	Boolean	Indica se il codice sconto è stato rifiutato.

CartDiscount::Percentage

Metodi di script che utilizzano l'oggetto CartDiscount::Percentage

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

CartDiscount::Shipping

Metodi script che utilizzano 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 message.
.rejected?	Boolean	Indica se il codice sconto è stato rifiutato.

Customer

Metodi script che utilizzano l'oggetto Customer

Metodo	Tipo restituito	Descrizione
.id	Integer	Restituisce il numero ID del cliente.
.email	String	Restituisce l'indirizzo email del cliente.
.tags	List<Tag>	Restituisce un elenco di stringhe che rappresentano eventuali tag impostati per 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	Restituisce un valore booleano che indica se il cliente accetta le comunicazioni di marketing.

LineItem

Metodi script che utilizzano l'oggetto LineItem

Metodo	Tipo restituito	Descrizione
.grams	grams	Restituisce il peso totale della voce.
.line_price	Money	Il prezzo della voce.
.discounted?	Boolean	Restituisce un valore booleano che indica se al prezzo di una voce è stato applicato uno sconto tramite script o uno sconto applicato manualmente. L'uso di codici sconto non influisce sul valore restituito.
.properties	hash	Restituisce le proprietà specificate per questa voce.
.variant	Variant	Restituisce la variante di prodotto specifica rappresentata dalla voce.
.quantity	Integer	Restituisce la quantità di questa voce.
.selling_plan_id	Integer	Restituisce l'ID del piano di vendita per la 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 che utilizzano l'oggetto List

Metodo	Tipo restituito	Descrizione
.new	List	Crea un nuovo oggetto per rappresentare un elenco.
.[]	Elemento o nil	Restituisce l'elemento in corrispondenza dell'indice specificato.
.&	List	Restituisce un nuovo elenco contenente gli elementi comuni ai due elenchi, senza duplicati.
.delete_if	List	Elimina elementi utilizzando un blocco di codice facoltativo. Consulta la documentazione relativa al metodo delete_if di Ruby.
.empty?	Boolean	Restituisce true se l'elenco non contiene elementi.
.first	Elemento 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 viene fornito un blocco anziché un argomento, restituisce l'indice del primo elemento per cui il blocco è true.
.rindex(*args, &block)	int o nil	Restituisce l'indice dell'ultimo elemento dell'elenco. Se viene fornito un blocco anziché un argomento, restituisce l'indice del primo elemento per cui il blocco è true.
.last	Elemento o nil	Restituisce l'ultimo elemento o nil se l'elenco è vuoto.
.length	int	Restituisce il numero di elementi nell'elenco.
.size	int	Alias di length.
.each(*args, &block)	List	Chiama un blocco una volta per ogni elemento nell'elenco, passando l'elemento come parametro al blocco.

ShippingAddress

Metodi script che utilizzano l'oggetto ShippingAddress

Metodo	Tipo restituito	Descrizione
.name	string	Restituisce il nome della persona associata all'indirizzo di spedizione.
.address1	string	Restituisce la parte dell'indirizzo di spedizione relativa alla via.
.address2	string	Restituisce il campo aggiuntivo facoltativo dell'indirizzo di spedizione.
.phone	string	Restituisce il numero di telefono dell'indirizzo di spedizione.
.city	string	Restituisce la città dell'indirizzo di spedizione.
.zip	string	Restituisce il CAP dell'indirizzo di spedizione.
.province	string	Restituisce la provincia/stato dell'indirizzo di spedizione.
.province_code	string	Restituisce il valore abbreviato della provincia/stato dell'indirizzo di spedizione.
.country_code	string	Restituisce il valore abbreviato del paese dell'indirizzo di spedizione.

Money

Metodi script che utilizzano l'oggetto Money

Metodo	Tipo restituito	Descrizione
.derived_from_presentment(customer_cents:X)	Money	Converte un importo (in centesimi) dalla valuta di presentazione del cliente alla valuta del tuo negozio. Questo metodo accetta il parametro customer_cents, che a sua volta accetta 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 un prezzo pari a zero.
+	Money	Somma 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, ovvero 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 $.

Variante

Metodi di script che utilizzano l'oggetto Variant

Metodo	Tipo restituito	Descrizione
.id	Integer	Restituisce il numero ID della variante.
.price	Money	Restituisce il prezzo unitario della variante.
.product	Prodotto	Restituisce il prodotto associato della variante.
.skus	Lista<String>	Restituisce gli SKU (Stock Keeping Unit) della variante, spesso utilizzati per il tracciamento delle scorte.
.title	String	Restituisce il titolo della variante.

Prodotto

Metodi di script che utilizzano l'oggetto Product

Metodo	Tipo restituito	Descrizione
.id	Integer	Restituisce il numero ID 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 classificazione con cui è possibile aggiungere tag a un prodotto, comunemente utilizzata per filtrare ed effettuare ricerche.
.vendor	String	Restituisce il venditore di questo prodotto.

Kernel

Kernel è un modulo Ruby incluso in ogni classe. Di conseguenza, i suoi metodi sono disponibili per ogni oggetto. Questi metodi agiscono allo stesso modo delle funzioni globali in altre lingue.

Metodi di script che utilizzano l'oggetto Kernel

Metodo	Tipo restituito	Descrizione
.exit	nessuno	Termina l'esecuzione dello script corrente senza errori. Se viene eseguito prima che qualsiasi valore venga assegnato a Output.cart, lo script non ha alcun effetto. Questo è un modo utile per terminare gli script, ad esempio, se il cliente non è idoneo per l'esecuzione dello script.

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 per voci:

Carrello

Metodi di script che utilizzano l'oggetto Cart negli script per voci

Metodo	Tipo restituito	Descrizione
.subtotal_price_was	Money	Restituisce il subtotale del carrello prima dell'applicazione di qualsiasi sconto.
.subtotal_price_changed?	Boolean	Indica se il subtotale è cambiato.

LineItem

Metodi di script che utilizzano l'oggetto LineItem negli script per voci

Metodo	Tipo restituito	Descrizione
.change_line_price(Money new_price, { message: String })	Money	Modifica il prezzo della voce impostandolo sull'importo specificato. È richiesto un messaggio. new_price deve essere inferiore al prezzo corrente.
.original_line_price	Money	Restituisce il prezzo originale della voce prima dell'applicazione di script e sconti.
.line_price_was	Money	Restituisce il prezzo della voce prima che lo script corrente vi applicasse delle modifiche.
.line_price_changed?	Boolean	Indica se il prezzo della voce è cambiato.
.change_properties(hash new_properties, { message: String })	hash	Imposta nuove proprietà per una voce. L'hash delle proprietà originali viene archiviato in properties_was e l'hash delle proprietà che viene passato al metodo diventa la nuova serie di proprietà per la voce.
.properties_was	hash	Restituisce l'hash delle proprietà originali della voce prima dell'applicazione di qualsiasi modifica.
.properties_changed?	Boolean	Indica se le proprietà della voce sono state modificate.
.split({ take: Integer })	LineItem	Suddivide una voce in due voci. take specifica la quantità da rimuovere dalla voce originale per creare la nuova voce.

Esempio di .split

Questo script di esempio suddivide una voce chiamata original_line_item in due voci. La nuova voce ha una quantità pari a 1 (specificata da take: 1). Lo script applica quindi un prezzo scontato alla nuova voce con il messaggio «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

Variante

Metodi di script che utilizzano l'oggetto Variant negli script per voci

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.

Metodi di spedizione

I seguenti metodi sono utilizzabili negli script di spedizione:

Input

Metodi di script che utilizzano 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 di script che utilizzano l'oggetto ShippingRateList negli script di spedizione

Metodo	Tipo restituito	Descrizione
.delete_if	ShippingRateList	Elimina le tariffe di spedizione utilizzando un blocco di codice facoltativo. Vedi 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 facoltativo. Vedi la documentazione per il metodo sort! di Ruby.
.sort_by!	ShippingRateList	Ordina le tariffe di spedizione utilizzando un blocco di codice facoltativo. Vedi la documentazione per il metodo sort_by! di Ruby.

ShippingRate

Metodi di script che utilizzano l'oggetto ShippingRate negli script di spedizione

Metodo	Tipo restituito	Descrizione
.code	String	Restituisce il codice della tariffa di spedizione.
.markup	Money	Restituisce il ricarico 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 modificata.
.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 di 0. È necessario un messaggio.
.phone_required?	Boolean	Restituisce true se per ottenere la tariffa di spedizione è richiesto un numero di telefono, o false in caso contrario.

Metodi di pagamento

I seguenti metodi sono utilizzabili negli script di pagamento:

Input

Metodi di script che utilizzano l'oggetto Input negli script di pagamento

Metodo	Tipo restituito	Descrizione
.payment_gateways	PaymentGatewaysList	Restituisce un elenco di tutti i canali di pagamento del negozio.

PaymentGatewayList

Metodi di script che utilizzano l'oggetto PaymentGatewayList negli script di pagamento

Metodo	Tipo restituito	Descrizione
.delete_if	PaymentGatewayList	Elimina i canali di pagamento utilizzando un blocco di codice facoltativo. Vedi la documentazione per il metodo delete_if di Ruby.
.sort!	PaymentGatewayList	Ordina i canali di pagamento utilizzando l'operatore di confronto o un blocco di codice facoltativo. Vedi la documentazione per il metodo sort! di Ruby.
.sort_by!	PaymentGatewayList	Ordina i canali di pagamento utilizzando un blocco di codice facoltativo. Vedi la documentazione per il metodo sort_by! di Ruby.

PaymentGateway

Metodo	Tipo restituito	Descrizione
.name	String	Restituisce il nome del canale di pagamento.
.enabled_card_brands	Lista<String>	Se il canale di pagamento supporta le carte di credito, restituisce un elenco dei tipi di carta di credito accettati dal negozio. Se il canale 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 logo non possono essere rinominati.

Esempi

Nell'esempio di script per voce seguente, quando un cliente ordina un prodotto che non è un buono regalo, il prezzo del prodotto viene ridotto di 9 $. Inoltre, viene mostrato l'importo totale che il cliente ha speso in tutte le visite 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

Scopri di più

Scopri di più su:

• Nozioni di base su Ruby
• Creazione di script
• Test e debug degli script
• Aggiornamento dei modelli Liquid per gli script
• script Shopify