Referència de l'API de Shopify Scripts

Els scripts s'escriuen amb una API de Ruby que t'ofereix un gran control i flexibilitat.

Hi ha diferents tipus d'scripts. A un script se li assigna un tipus quan el crees a l'aplicació Script Editor, depenent de la plantilla d'script amb la qual decideixis començar:

Scripts de partida

Els scripts de partida afecten les partides del carretó, i poden canviar-ne els preus i concedir descomptes. Aquests scripts s'executen quan es fa un canvi al carretó.

Els scripts de partida que apliquen un descompte a una subscripció només s'apliquen al primer pagament de la subscripció. L'script no aplica descomptes als pagaments posteriors.

Alguns mètodes només es poden utilitzar en scripts de partida.

Scripts d'enviament

Els scripts d'enviament interactuen amb l'enviament, i poden canviar les formes d'enviament i concedir descomptes en els costos d'enviament. Aquests scripts s'executen quan el pagament arriba a la pàgina d'opcions d'enviament.

Els scripts d'enviament que apliquen un descompte al cost d'enviament d'una subscripció només s'apliquen al primer pagament de la subscripció. L'script no aplica descomptes als pagaments posteriors.

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

Scripts de pagament

Els scripts de pagament interactuen amb els pagaments, i poden canviar el nom, ocultar i reordenar les passarel·les de pagament. Tingues en compte que els scripts de pagament no interactuen amb les passarel·les de pagament que es mostren abans de la pantalla de pagament, com ara Apple Pay. Aquests scripts s'executen quan el pagament arriba a la pàgina de pagament.

Alguns mètodes només es poden utilitzar en scripts de pagament.

En aquesta pàgina

Mètodes generals

Els mètodes següents es poden utilitzar en qualsevol tipus d'script:

Entrada

Mètodes d'entrada d'script
Mètode	Tipus de retorn	Descripció
.cart	Cart	Retorna un objecte de carretó mutable.
.locale	cadena	Retorna la configuració regional del client. Per exemple, `en`, `fr` o `pt-BR`.

Carretó

L'objecte de carretó només està disponible a la botiga en línia. Algunes compres abandonades tenen accés a l'objecte de carretó. Tot i això, si s'ha tancat un pagament i després un client visita la compra abandonada, se l'envia al pagament emplenat prèviament i l'objecte de carretó ja no existeix. Això és perquè el correu electrònic de compra abandonada ha omès l'aparador.

Mètode Tipus de retorn Descripció

.customer Customer Retorna el propietari del carretó (si n'hi ha).

.shipping_address ShippingAddress Retorna l'adreça d'enviament del propietari del carretó (si n'hi ha).

.discount_code

varia

Mètodes d'script que utilitzen l'objecte de carretó
Mètode	Tipus de retorn	Descripció
.customer	Customer	Retorna el propietari del carretó (si n'hi ha).
.shipping_address	ShippingAddress	Retorna l'adreça d'enviament del propietari del carretó (si n'hi ha).
.discount_code	varia	Retorna: `nil` si el carretó no té cap codi de descompte `CartDiscount::FixedAmount` si el carretó té un import de descompte fix `CartDiscount::Percentage` si el carretó té un descompte percentual `CartDiscount::Shipping` si el carretó té un descompte d'enviament Retorna un sol codi de descompte (consulta les Limitacions) `discount_code` està present si s'ha aplicat un descompte al carretó. Això no significa necessàriament que el preu del carretó canviï. Per exemple, si s'aplica un descompte als carretons de més de 50 $ i un script redueix el preu del carretó per sota dels 50 $, `discount_code` continuarà present, però el preu del carretó no canviarà. <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><LineItem></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><String></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>

Retorna:

nil si el carretó no té cap codi de descompte
CartDiscount::FixedAmount si el carretó té un import de descompte fix
CartDiscount::Percentage si el carretó té un descompte percentual
CartDiscount::Shipping si el carretó té un descompte d'enviament
Retorna un sol codi de descompte (consulta les Limitacions)

discount_code està present si s'ha aplicat un descompte al carretó. Això no significa necessàriament que el preu del carretó canviï. Per exemple, si s'aplica un descompte als carretons de més de 50 $ i un script redueix el preu del carretó per sota dels 50 $, discount_code continuarà present, però el preu del carretó no canviarà.

<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

Mètodes d'script que utilitzen l'objecte CartDiscount::FixedAmount
Mètode	Tipus de retorn	Descripció
.code	Cadena	Retorna el codi de descompte que s'ha utilitzat per aplicar el descompte.
.amount	Money	Retorna l'import monetari del descompte.
.reject({ message: String })	nil	Rebutja el codi de descompte aplicat al carretó. Es requereix un `message`.
.rejected?	Booleà	Retorna si s'ha rebutjat el codi de descompte.

CartDiscount::Percentage

Mètodes d'script que utilitzen l'objecte CartDiscount::Percentage
Mètode	Tipus de retorn	Descripció
.code	Cadena	Retorna el codi de descompte que s'ha utilitzat per aplicar el descompte.
.percentage	Decimal	Retorna el percentatge del descompte.
.reject({ message: String })	nil	Rebutja el codi de descompte aplicat al carretó. Es requereix un `message`.
.rejected?	Booleà	Retorna si s'ha rebutjat el codi de descompte.

CartDiscount::Shipping

Mètodes d'script que utilitzen l'objecte CartDiscount::Shipping
Mètode	Tipus de retorn	Descripció
.code	Cadena	Retorna el codi de descompte que s'ha utilitzat per aplicar el descompte.
.reject({ message: String })	nil	Rebutja el codi de descompte aplicat al carretó. Es requereix un `message`.
.rejected?	Booleà	Retorna si s'ha rebutjat el codi de descompte.

Customer

Mètodes d'script que utilitzen l'objecte Customer
Mètode	Tipus de retorn	Descripció
.id	Enter	Retorna el número d'ID del client.
.email	Cadena	Retorna l'adreça de correu electrònic del client.
.tags	List<Tag>	Retorna una llista de cadenes que representen qualsevol de les etiquetes establertes per a un client.
.orders_count	Enter	Retorna el nombre total de comandes que un client ha fet.
.total_spent	Money	Retorna l'import total que el client ha gastat en totes les comandes.
.accepts_marketing?	Booleà	Retorna si el client accepta màrqueting.

LineItem

Mètodes d'script que utilitzen l'objecte LineItem
Mètode	Tipus de retorn	Descripció
.grams	grams	Retorna el pes total de la partida.
.line_price	Money	El preu de la partida.
.discounted?	Booleà	Retorna si el preu d'una partida s'ha rebaixat mitjançant un script o bé si se li ha aplicat un descompte manualment. L'ús de codis de descompte no n'afecta el valor de retorn.
.properties	hash	Retorna les propietats que es van especificar per a aquesta partida.
.variant	Variant	Retorna la variant del producte específica representada per la partida.
.quantity	Enter	Retorna la quantitat d'aquesta partida.
.selling_plan_id	Enter	Retorna l'ID del pla de venda per a la partida. Aquest mètode és útil quan la botiga ven subscripcions i vols que l'script detecti quan una variant del producte es ven com una subscripció.

List

Mètodes d'script que utilitzen l'objecte List
Mètode	Tipus de retorn	Descripció
.new	List	Crea un objecte nou per representar una llista.
.[]	Element o nil	Retorna l'element a l'índex especificat.
.&	List	Retorna una llista nova que conté elements comuns a les dues llistes, sense duplicats.
.delete_if	List	Suprimeix elements mitjançant un bloc de codi opcional. Consulta la documentació del mètode `delete_if` de Ruby.
.empty?	Booleà	Retorna `true` si la llista no conté cap element.
.first	Element o nil	Retorna el primer element o `nil` si la llista està buida.
.index(*args, &block)	int o nil	Retorna l'índex del primer element de la llista. Si es proporciona un bloc en comptes d'un argument, retorna l'índex del primer element per al qual el bloc és cert.
.rindex(*args, &block)	int o nil	Retorna l'índex de l'últim element de la llista. Si es proporciona un bloc en comptes d'un argument, retorna l'índex del primer element per al qual el bloc és cert.
.last	Element o nil	Retorna l'últim element o `nil` si la llista està buida.
.length	int	Retorna el nombre d'elements a la llista.
.size	int	Àlies de length.
.each(*args, &block)	List	Crida un bloc una vegada per a cada element de la llista i passa l'element com a paràmetre al bloc.

ShippingAddress

Mètodes d'script que utilitzen l'objecte ShippingAddress
Mètode	Tipus de retorn	Descripció
.name	cadena	Retorna el nom de la persona associada a l'adreça d'enviament.
.address1	cadena	Retorna la part de l'adreça postal de l'adreça d'enviament.
.address2	cadena	Retorna el camp addicional opcional de la part de l'adreça postal de l'adreça d'enviament.
.phone	cadena	Retorna el número de telèfon de l'adreça d'enviament.
.city	cadena	Retorna la ciutat de l'adreça d'enviament.
.zip	cadena	Retorna el codi postal de l'adreça d'enviament.
.province	cadena	Retorna la província/estat de l'adreça d'enviament.
.province_code	cadena	Retorna el valor abreujat de la província/estat de l'adreça d'enviament.
.country_code	cadena	Retorna el valor abreujat del país de l'adreça d'enviament.

Money

Mètodes d'script que utilitzen l'objecte Money
Mètode	Tipus de retorn	Descripció
.derived_from_presentment(customer_cents:X)	Money	Converteix un import (en cèntims) de la moneda local del client (moneda mostrada al client) a la moneda de la teva botiga. Aquest mètode accepta el paràmetre `customer_cents`, que admet un número en cèntims. Per exemple, `Money.derived_from_presentment(customer_cents: 500)`.
.new	Money	Crea un objecte nou per representar un preu.
.zero	Money	Crea un objecte nou amb un preu igual a zero.
+	Money	Suma dos objectes `Money`.
-	Money	Resta un objecte `Money` d'un altre.
*	Money	Multiplica un objecte `Money` per un número.

Exemples de Money

Money.new(cents: 1000)

Crea un objecte Money que representa 1.000 cèntims o 10 $.

Money.new(cents: 100) * 50

Crea un objecte Money que representa 1 $, i després multiplica l'import per 50. Retorna un objecte Money que representa 50 $.

Variant

Mètodes d'script que utilitzen l'objecte Variant
Mètode	Tipus de retorn	Descripció
.id	Enter	Retorna el número d'ID de la variant.
.price	Money	Retorna el preu unitari de la variant.
.product	Product	Retorna el producte associat de la variant.
.skus	List<String>	Retorna les unitats de manteniment d'estoc (SKU) de la variant, que sovint s'utilitzen per fer un seguiment de l'estoc.
.title	Cadena	Retorna el títol de la variant.

Producte

Mètodes d'script que utilitzen l'objecte Product
Mètode	Tipus de retorn	Descripció
.id	Enter	Retorna el número d'ID del producte.
.gift_card?	Booleà	Retorna si el producte és un val regal.
.tags	List<Tag>	Retorna una llista de cadenes que representen les etiquetes que s'han establert per a aquest producte.
.product_type	Cadena	Una categorització amb la qual es pot etiquetar un producte; s'utilitza habitualment per filtrar i cercar.
.vendor	Cadena	Retorna el proveïdor d'aquest producte.

Kernel

Kernel és un mòdul de Ruby que s'inclou en totes les classes. Per tant, els seus mètodes estan disponibles per a qualsevol objecte. Aquests mètodes actuen de la mateixa manera que les funcions globals en altres llenguatges.

Mètodes d'script que utilitzen l'objecte Kernel
Mètode	Tipus de retorn	Descripció
.exit	cap	Finalitza l'execució de l'script actual sense errors. Si s'executa abans d'assignar res a `Output.cart`, l'script no té cap efecte. Aquesta és una manera útil de sortir dels scripts, per exemple, si el client no compleix els requisits per executar l'script.

Exemple de Kernel

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

Mètodes de la partida

Els mètodes següents només es poden utilitzar als scripts de partida:

Carretó

Mètodes d'script que utilitzen l'objecte Cart als scripts de partida
Mètode	Tipus de retorn	Descripció
.subtotal_price_was	Money	Retorna el preu del total parcial del carretó abans que s'apliqués cap descompte.
.subtotal_price_changed?	Booleà	Retorna si el preu del total parcial ha canviat.

LineItem

Mètodes d'script que utilitzen l'objecte LineItem als scripts de partida
Mètode	Tipus de retorn	Descripció
.change_line_price(Money new_price, { message: String })	Money	Canvia el preu de la partida a l'import especificat. Es requereix un `message`. El `new_price` ha de ser inferior al preu actual.
.original_line_price	Money	Retorna el preu original de la partida abans que s'apliquessin els scripts i els descomptes.
.line_price_was	Money	Retorna el preu de la partida abans que l'script actual hi apliqués cap canvi.
.line_price_changed?	Booleà	Retorna si el preu de la partida ha canviat.
.change_properties(hash new_properties, { message: String })	hash	Estableix propietats noves per a una partida. El hash de propietats original s'emmagatzema a `properties_was` i el hash de propietats que es passa al mètode es converteix en les propietats noves de la partida.
.properties_was	hash	Retorna el hash de propietats original de la partida abans que s'hi apliqués cap canvi.
.properties_changed?	Booleà	Retorna si les propietats de la partida han canviat.
.split({ take: Integer })	LineItem	Divideix una partida en dues. `take` especifica quina quantitat cal eliminar de la partida original per crear-ne la nova.

Exemple de .split

Aquest script d'exemple divideix una partida anomenada original_line_item en dues partides. La nova partida té una quantitat d'1 (especificat per take: 1). A continuació, l'script aplica un preu amb descompte a la nova partida amb el missatge "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

Variant

Mètodes d'script que utilitzen l'objecte Variant en scripts de partides
Mètode	Tipus de retorn	Descripció
.compare_at_price	Money	Retorna el preu de referència de la variant. Retorna `nil` si la variant no té cap preu de referència.

Formes d'enviament

Els mètodes següents es poden utilitzar en scripts d'enviament:

Entrada

Mètodes d'script que utilitzen l'objecte Input en scripts d'enviament
Mètode	Tipus de retorn	Descripció
.shipping_rates	ShippingRateList	Retorna una llista de tots els preus d'enviament.

ShippingRateList

Mètodes d'script que utilitzen l'objecte ShippingRateList en scripts d'enviament
Mètode	Tipus de retorn	Descripció
.delete_if	ShippingRateList	Suprimeix preus d'enviament utilitzant un bloc de codi opcional. Consulta la documentació del mètode `delete_if` de Ruby.
.sort!	ShippingRateList	Ordena els preus d'enviament utilitzant l'operador de comparació o un bloc de codi opcional. Consulta la documentació del mètode `sort!` de Ruby.
.sort_by!	ShippingRateList	Ordena els preus d'enviament utilitzant un bloc de codi opcional. Consulta la documentació del mètode `sort_by!` de Ruby.

ShippingRate

Mètodes d'script que utilitzen l'objecte ShippingRate en scripts d'enviament
Mètode	Tipus de retorn	Descripció
.code	Cadena	Retorna el codi del preu d'enviament.
.markup	Money	Retorna el marge comercial d'un preu d'enviament, si escau.
.name	Cadena	Retorna el nom del preu d'enviament. Es pot modificar utilitzant el mètode `change_name`.
.price	Money	Retorna l'import del preu d'enviament.
.source	Cadena	Retorna l'origen (el transportista) associat al preu d'enviament, si escau. No es pot modificar.
.change_name(String new_name)	Cadena	Canvia el nom (màxim 255 caràcters) del preu d'enviament. L'origen no es pot canviar, suprimir ni ocultar.
.apply_discount(Money discount, { message: String })	Money	Aplica un descompte de l'import fix especificat. El preu no es pot reduir a menys de 0. És obligatori incloure-hi un missatge.
.phone_required?	Booleà	Retorna `true` si es requereix un número de telèfon per obtenir el preu d'enviament, o `false` si no es requereix cap número de telèfon.

Formes de pagament

Els mètodes següents es poden utilitzar en scripts de pagament:

Entrada

Mètodes d'script que utilitzen l'objecte Input en scripts de pagament
Mètode	Tipus de retorn	Descripció
.payment_gateways	PaymentGatewaysList	Retorna una llista de totes les passarel·les de pagament de la botiga.

PaymentGatewayList

Mètodes d'script que utilitzen l'objecte PaymentGatewayList en scripts de pagament
Mètode	Tipus de retorn	Descripció
.delete_if	PaymentGatewayList	Suprimeix passarel·les de pagament utilitzant un bloc de codi opcional. Consulta la documentació del mètode `delete_if` de Ruby.
.sort!	PaymentGatewayList	Ordena les passarel·les de pagament utilitzant l'operador de comparació o un bloc de codi opcional. Consulta la documentació del mètode `sort!` de Ruby.
.sort_by!	PaymentGatewayList	Ordena les passarel·les de pagament utilitzant un bloc de codi opcional. Consulta la documentació del mètode `sort_by!` de Ruby.

PaymentGateway

Mètode	Tipus de retorn	Descripció
.name	Cadena	Retorna el nom de la passarel·la de pagament.
.enabled_card_brands	List<String>	Si la passarel·la de pagament admet targetes de crèdit, retorna una llista dels tipus de targeta de crèdit que la botiga accepta. Si la passarel·la no admet targetes de crèdit, retorna una llista buida.
.change_name(String new_name)	Cadena	Canvia el nom de la passarel·la de pagament. Les passarel·les de pagament amb logotip no es poden canviar de nom.

Exemples

En l'exemple d'script de partida següent, quan un client fa una comanda d'un producte que no és un val regal, el preu del producte es redueix 9 $. A més, es mostra l'import total que ha gastat el client en totes les visites a la teva botiga:

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

Saber-ne més

Més informació sobre: