Referencia da API de Shopify Scripts

Os scripts escríbense cunha API de Ruby que che ofrece un gran control e flexibilidade.

Requisito do plan

A partir do 30 de xuño de 2026, suspendeuse Shopify Scripts. Todos os scripts que aínda estaban publicados na túa tenda desactiváronse e xa non funcionan. Para volver crear estas personalizacións, cambia a Shopify Functions. Obtén máis información sobre como pasar de Shopify Scripts a Shopify Functions.

Existen diferentes tipos de scripts. Asígnase un tipo a un script ao crealo na aplicación Script Editor, segundo o modelo de script co que decidas comezar:

Scripts de artigos de liña

Os scripts de artigos de liña afectan aos artigos de liña no carro e poden modificar prezos e conceder descontos. Estes scripts execútanse cando se fai un cambio no carro.

Os scripts de artigos de liña que aplican un desconto a unha subscrición unicamente se aplican ao primeiro pagamento da subscrición. O script non aplica o desconto nos pagamentos posteriores.

Algúns métodos só se poden usar nos scripts de artigos de liña.

Scripts de envío

Os scripts de envío interactúan co envío e poden modificar os métodos de envío e conceder descontos nas tarifas de envío. Estes scripts execútanse cando o proceso de pagamento chega á páxina de opcións de envío.

Os scripts de envío que aplican un desconto á tarifa de envío dunha subscrición unicamente se aplican ao primeiro pagamento desta. O script non aplica descontos aos pagamentos posteriores.

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

Scripts de pagamento

Os scripts de pagamento interactúan cos pagamentos e poden cambiar o nome, ocultar e reordenar as pasarelas de pago. Ten en conta que os scripts de pagamento non interactúan con aquelas pasarelas de pago que se mostran antes da pantalla de pagamento, como Apple Pay. Estes scripts execútanse cando o proceso de pagamento chega á páxina de pagamento.

Algúns métodos só se poden usar nos scripts de pagamento.

Métodos xerais

Os seguintes métodos pódense usar en calquera tipo de script:

Entrada

Métodos de entrada do script

Método	Tipo de retorno	Descrición
.cart	Cart	Devolve un obxecto de carro mutábel.
.locale	cadea	Devolve a configuración rexional do cliente. Por exemplo, en, fr ou pt-BR.

Carro

O obxecto de carro só está dispoñible na tenda en liña. Algúns pasos por caixa abandonados teñen acceso a este obxecto. Non obstante, se se pecha un proceso de pagamento e o cliente visita despois o paso por caixa abandonado, enviaráselle ao proceso de pagamento cuberto previamente e o obxecto de carro deixará de existir. Isto sucede porque o correo electrónico de pago abandonado omitiu o escaparate.

Métodos de script que usan o obxecto Cart

Método	Tipo de retorno	Descrición
.customer	Customer	Devolve o propietario do carro (se o hai).
.shipping_address	ShippingAddress	Devolve o enderezo de envío do propietario do carro (se o hai).
.discount_code	varía	Devolve: nil se o carro non ten ningún código de desconto CartDiscount::FixedAmount se o carro ten un importe de desconto fixo CartDiscount::Percentage se o carro ten unha porcentaxe de desconto CartDiscount::Shipping se o carro ten un desconto de envío Devolve un único código de desconto (consulta Limitacións) discount_code está presente se se aplicou un desconto ao carro. Isto non significa necesariamente que o prezo do carro cambie. Por exemplo, se se aplica un desconto en carros superiores a 50 $ e un script reduce o prezo do carro por debaixo de 50 $, discount_code seguirá estando presente, pero o prezo do carro non cambiará. <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étodos de script que usan o obxecto CartDiscount::FixedAmount

Método	Tipo de retorno	Descrición
.code	Cadea	Devolve o código de desconto que se usou para aplicar o desconto.
.amount	Money	Devolve o importe monetario do desconto.
.reject({ message: String })	nil	Rexeita o código de desconto aplicado ao carro. Requírese unha message.
.rejected?	Booleano	Devolve se o código de desconto foi rexeitado.

CartDiscount::Percentage

Métodos de script que usan o obxecto CartDiscount::Percentage

Método	Tipo de retorno	Descrición
.code	Cadea	Devolve o código de desconto que se usou para aplicar o desconto.
.percentage	Decimal	Devolve a cantidade porcentual do desconto.
.reject({ message: String })	nil	Rexeita o código de desconto aplicado ao carro. Requírese unha message.
.rejected?	Booleano	Devolve se o código de desconto foi rexeitado.

CartDiscount::Shipping

Métodos de script que usan o obxecto CartDiscount::Shipping

Método	Tipo de retorno	Descrición
.code	Cadea	Devolve o código de desconto que se usou para aplicar o desconto.
.reject({ message: String })	nil	Rexeita o código de desconto aplicado ao carro. Requírese unha message.
.rejected?	Booleano	Devolve se o código de desconto foi rexeitado.

Customer

Métodos de script que usan o obxecto Customer

Método	Tipo de retorno	Descrición
.id	Enteiro	Devolve o número de ID do cliente.
.email	Cadea	Devolve o enderezo de correo electrónico do cliente.
.tags	List<Tag>	Devolve unha lista de cadeas que representan calquera etiqueta establecida para un cliente.
.orders_count	Enteiro	Devolve o número total de pedidos que fixo un cliente.
.total_spent	Money	Devolve o importe total que o cliente gastou en todos os pedidos.
.accepts_marketing?	Booleano	Devolve se o cliente acepta o márketing.

LineItem

Métodos de script que usan o obxecto LineItem

Método	Tipo de retorno	Descrición
.grams	gramos	Devolve o peso total do artigo de liña.
.line_price	Money	O prezo do artigo de liña.
.discounted?	Booleano	Devolve se o prezo dun artigo de liña foi rebaixado por un script ou por un desconto aplicado manualmente. O uso de códigos de desconto non afecta ao valor de retorno.
.properties	hash	Devolve as propiedades que se especificaron para este artigo de liña.
.variant	Variant	Devolve a variante de produto específica representada polo artigo de liña.
.quantity	Enteiro	Devolve a cantidade deste artigo de liña.
.selling_plan_id	Enteiro	Devolve o ID do plan de vendas para o artigo de liña. Este método é útil cando a tenda vende subscricións e queres que o script detecte cando unha variante de produto se vende como unha subscrición.

List

Métodos de script que usan o obxecto List

Método	Tipo de retorno	Descrición
.new	List	Crea un novo obxecto para representar unha lista.
.[]	Elemento ou nil	Devolve o elemento no índice especificado.
.&	List	Devolve unha nova lista que contén elementos comúns ás dúas listas, sen duplicados.
.delete_if	List	Elimina elementos usando un bloque de código opcional. Consulta a documentación do método delete_if de Ruby.
.empty?	Booleano	Devolve true se a lista non contén elementos.
.first	Elemento ou nil	Devolve o primeiro elemento ou nil se a lista está baleira.
.index(*args, &block)	int ou nil	Devolve o índice do primeiro elemento da lista. Se se proporciona un bloque en lugar dun argumento, devolve o índice do primeiro elemento para o cal o bloque é verdadeiro.
.rindex(*args, &block)	int ou nil	Devolve o índice do último elemento da lista. Se se proporciona un bloque en lugar dun argumento, devolve o índice do primeiro elemento para o cal o bloque é verdadeiro.
.last	Elemento ou nil	Devolve o último elemento ou nil se a lista está baleira.
.length	int	Devolve o número de elementos da lista.
.size	int	Alias para length.
.each(*args, &block)	List	Chama a un bloque unha vez por cada elemento da lista, pasando o elemento como parámetro ao bloque.

ShippingAddress

Métodos de script que usan o obxecto ShippingAddress

Método	Tipo de retorno	Descrición
.name	cadea	Devolve o nome da persoa asociada ao enderezo de envío.
.address1	cadea	Devolve a parte da rúa do enderezo de envío.
.address2	cadea	Devolve o campo adicional opcional da parte da rúa do enderezo de envío.
.phone	cadea	Devolve o número de teléfono do enderezo de envío.
.city	cadea	Devolve a cidade do enderezo de envío.
.zip	cadea	Devolve o código ZIP do enderezo de envío.
.province	cadea	Devolve a provincia/estado do enderezo de envío.
.province_code	cadea	Devolve o valor abreviado da provincia/estado do enderezo de envío.
.country_code	cadea	Devolve o valor abreviado do país do enderezo de envío.

Money

Métodos de script que usan o obxecto Money

Método	Tipo de retorno	Descrición
.derived_from_presentment(customer_cents:X)	Money	Converte un importe (en céntimos) da moeda local do cliente (moeda de presentación) á moeda da túa tenda. Este método acepta o parámetro customer_cents, que acepta un número en céntimos. Por exemplo, Money.derived_from_presentment(customer_cents: 500).
.new	Money	Crea un novo obxecto para representar un prezo.
.zero	Money	Crea un novo obxecto cun prezo de cero.
+	Money	Suma dous obxectos Money.
-	Money	Resta un obxecto Money doutro.
*	Money	Multiplica un obxecto Money por un número.

Exemplos de Money

Money.new(cents: 1000)

Crea un obxecto Money que representa 1000 céntimos ou 10 $.

Money.new(cents: 100) * 50

Crea un obxecto Money que representa 1 $ e, a continuación, multiplica ese importe por 50. Devolve un obxecto Money que representa 50 $.

Variant

Métodos de script que usan o obxecto Variant

Método	Tipo de retorno	Descrición
.id	Enteiro	Devolve o número de ID da variante.
.price	Money	Devolve o prezo unitario da variante.
.product	Product	Devolve o produto asociado da variante.
.skus	List<String>	Devolve as unidades de mantemento de existencias (SKU) da variante, que a miúdo se usan para o seguimento do inventario.
.title	Cadea	Devolve o título da variante.

Product

Métodos de script que usan o obxecto Product

Método	Tipo de retorno	Descrición
.id	Enteiro	Devolve o número de ID do produto.
.gift_card?	Booleano	Devolve se o produto é unha tarxeta de agasallo.
.tags	List<Tag>	Devolve unha lista de cadeas que representan as etiquetas que están definidas para este produto.
.product_type	Cadea	Unha categorización coa que se pode etiquetar un produto e que adoita usarse para filtrar e buscar.
.vendor	Cadea	Devolve o provedor deste produto.

Kernel

Kernel é un módulo de Ruby que se inclúe en todas as clases. Como resultado, os seus métodos están dispoñibles para todos os obxectos. Estes métodos actúan do mesmo modo ca as funcións globais noutras linguaxes.

Métodos de script que usan o obxecto Kernel

Método	Tipo de retorno	Descrición
.exit	ningún	Finaliza a execución do script actual sen erro. Se isto se executa antes de que se asigne algo a Output.cart, o script non terá efecto. Este é un xeito útil de saír dos scripts; por exemplo, se o cliente non reúne os requisitos para executar o script.

Exemplo de Kernel

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

Métodos de artigo de liña

Os seguintes métodos só se poden usar en scripts de artigo de liña:

Carro

Métodos de script que usan o obxecto Cart en scripts de artigo de liña

Método	Tipo de retorno	Descrición
.subtotal_price_was	Money	Devolve o prezo subtotal do carro antes de que se aplicase ningún desconto.
.subtotal_price_changed?	Booleano	Devolve se cambiou o prezo subtotal.

LineItem

Métodos de script que usan o obxecto LineItem en scripts de artigo de liña

Método	Tipo de retorno	Descrición
.change_line_price(Money new_price, { message: String })	Money	Cambia o prezo do artigo de liña ao importe especificado. É necesario un message. new_price debe ser inferior ao prezo actual.
.original_line_price	Money	Devolve o prezo orixinal do artigo de liña antes de que se aplicasen scripts e descontos.
.line_price_was	Money	Devolve o prezo do artigo de liña antes de que o script actual aplicase cambios.
.line_price_changed?	Booleano	Devolve se cambiou o prezo do artigo de liña.
.change_properties(hash new_properties, { message: String })	hash	Establece novas propiedades para un artigo de liña. O hash de propiedades orixinais gárdase en properties_was e o hash de propiedades que se transmite ao método convértese nas novas propiedades para o artigo de liña.
.properties_was	hash	Devolve o hash de propiedades orixinal do artigo de liña antes de que se aplicase ningún cambio.
.properties_changed?	Booleano	Devolve se cambiaron as propiedades para o artigo de liña.
.split({ take: Integer })	LineItem	Divide un artigo de liña en dous. take especifica que cantidade eliminar do artigo de liña orixinal para crear o novo.

Exemplo de .split

Este script de exemplo divide un artigo de liña chamado original_line_item en dous artigos de liña. O novo artigo de liña ten unha cantidade de 1 (especificada por take: 1). A continuación, o script aplica un prezo rebaixado ao novo artigo de liña coa mensaxe "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étodos de script mediante o obxecto Variant en scripts de artigos de liña

Método	Tipo de retorno	Descrición
.compare_at_price	Money	Devolve o prezo de comparación da variante. Devolve nil se a variante non ten prezo de comparación.

Métodos de envío

Os seguintes métodos pódense utilizar en scripts de envío:

Entrada

Métodos de script mediante o obxecto Input en scripts de envío

Método	Tipo de retorno	Descrición
.shipping_rates	ShippingRateList	Devolve unha lista de todas as tarifas de envío.

ShippingRateList

Métodos de script mediante o obxecto ShippingRateList en scripts de envío

Método	Tipo de retorno	Descrición
.delete_if	ShippingRateList	Elimina as tarifas de envío usando un bloque de código opcional. Consulta a documentación do método delete_if de Ruby.
.sort!	ShippingRateList	Ordena as tarifas de envío mediante o operador de comparación ou un bloque de código opcional. Consulta a documentación do método sort! de Ruby.
.sort_by!	ShippingRateList	Ordena as tarifas de envío usando un bloque de código opcional. Consulta a documentación do método sort_by! de Ruby.

ShippingRate

Métodos de script mediante o obxecto ShippingRate en scripts de envío

Método	Tipo de retorno	Descrición
.code	Cadea	Devolve o código da tarifa de envío.
.markup	Money	Devolve a marxe de beneficio para unha tarifa de envío, de ser o caso.
.name	Cadea	Devolve o nome da tarifa de envío. Pódese modificar usando o método change_name.
.price	Money	Devolve o prezo da tarifa de envío.
.source	Cadea	Devolve a orixe (o transportista) asociada coa tarifa de envío, se é pertinente. Non se pode modificar.
.change_name(String new_name)	Cadea	Cambia o nome (máximo de 255 caracteres) da tarifa de envío. Non é posible cambiar, eliminar nin ocultar a orixe.
.apply_discount(Money discount, { message: String })	Money	Aplica un desconto do importe fixo especificado. O prezo non pode reducirse por debaixo de 0. Requírese unha mensaxe.
.phone_required?	Booleano	Devolve true se se require un número de teléfono para obter a tarifa de envío, ou false se non se precisa un número de teléfono.

Métodos de pagamento

Os seguintes métodos pódense utilizar en scripts de pagamento:

Entrada

Métodos de script mediante o obxecto Input en scripts de pagamento

Método	Tipo de retorno	Descrición
.payment_gateways	PaymentGatewaysList	Devolve unha lista de todas as pasarelas de pago na tenda.

PaymentGatewayList

Métodos de script mediante o obxecto PaymentGatewayList en scripts de pagamento

Método	Tipo de retorno	Descrición
.delete_if	PaymentGatewayList	Elimina pasarelas de pago mediante un bloque de código opcional. Consulta a documentación do método delete_if de Ruby.
.sort!	PaymentGatewayList	Ordena as pasarelas de pago mediante o operador de comparación ou un bloque de código opcional. Consulta a documentación do método sort! de Ruby.
.sort_by!	PaymentGatewayList	Ordena as pasarelas de pago usando un bloque de código opcional. Consulta a documentación do método sort_by! de Ruby.

PaymentGateway

Método	Tipo de retorno	Descrición
.name	Cadea	Devolve o nome da pasarela de pago.
.enabled_card_brands	List<String>	Se a pasarela de pago admite tarxetas de crédito, devolve unha lista dos tipos de tarxetas de crédito que acepta a tenda. Se a pasarela non admite tarxetas de crédito, devolve unha lista baleira.
.change_name(String new_name)	Cadea	Cambia o nome da pasarela de pago. As pasarelas de pago con logotipos non se poden renomear.

Exemplos

No seguinte exemplo de script de artigo de liña, cando un cliente fai un pedido dun produto que non é unha tarxeta de agasallo, o prezo do produto redúcese 9 $. Tamén se amosa o importe total que gastou o cliente durante as súas visitas á túa tenda:

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

Máis información

Máis información sobre:

• Fundamentos de Ruby
• Como crear scripts
• Como probar e depurar os teus scripts
• Como actualizar os teus modelos Liquid para os scripts
• Shopify Scripts