Riferimento API 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: `nil` se il carrello non ha codice sconto. `CartDiscount::FixedAmount` se il carrello ha un importo fisso di sconto. `CartDiscount::Percentage` se il carrello ha uno sconto percentuale. `CartDiscount::Shipping` se il carrello ha uno sconto di spedizione. Un singolo codice sconto (vedi Limitazioni) `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: