Referencia de la API de Shopify Scripts

Los scripts se escriben con una API de Ruby que ofrece un gran control y flexibilidad.

Requisito del plan

Shopify Scripts y la app Script Editor están disponibles solo para tiendas con el plan Shopify Plus. La app Script Editor ya no se puede descargar desde Shopify App Store.

El 30 de junio de 2026, Shopify Scripts se eliminará y dejará de funcionar. Si quieres seguir recibiendo soporte para los casos de uso actuales de Shopify Scripts, debes pasar a reemplazos compatibles de Shopify Functions para los scripts de pago, envío o de líneas de artículo existentes. Más información sobre cómo pasar de Shopify Scripts a Shopify Functions.

Hay distintos tipos de scripts. Cuando creas un script en la app Script Editor, se le asigna un tipo según la plantilla de script con la que decidas empezar:

Scripts de líneas de artículo

Los scripts de líneas de artículo afectan las líneas de artículo del carrito y pueden cambiar precios y otorgar descuentos. Estos scripts se ejecutan cuando se hace un cambio en el carrito.

Los scripts de líneas de artículo que aplican un descuento a una suscripción se aplican solo al primer pago de la suscripción. Los pagos posteriores no se descuentan con el script.

Algunos métodos solo se pueden usar en scripts de líneas de artículo.

Scripts de envío

Los scripts de envío interactúan con envío y pueden cambiar los métodos de envío y otorgar descuentos en las tarifas de envío. Estos scripts se ejecutan cuando el proceso de pago llega a la página de opciones de envío.

Los scripts de envío que descuentan la tarifa de envío de una suscripción se aplican solo al primer pago de la suscripción. Los pagos posteriores no se descuentan con el script.

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

Scripts de pago

Los scripts de pago interactúan con pagos y pueden cambiar el nombre, ocultar y reordenar pasarelas de pago. Ten en cuenta que los scripts de pago no interactúan con las pasarelas de pago que se muestran antes de la pantalla de pago, como Apple Pay. Estos scripts se ejecutan cuando el proceso de pago llega a la página de pago.

Algunos métodos solo se pueden usar en scripts de pago.

Métodos generales

Los siguientes métodos se pueden usar en cualquier tipo de script:

Entrada

Métodos de entrada de scripts

Método	Tipo de retorno	Descripción
.cart	Carrito	Devuelve un objeto de carrito modificable.
.locale	cadena	Devuelve la región del cliente. Por ejemplo, en, fr o pt-BR.

Carrito

El objeto de carrito solo está disponible en la tienda online. Algunos pedidos abandonados tienen acceso al objeto de carrito. Sin embargo, si se cerró un pago y luego un cliente visita el pedido abandonado, se le redirige al pago precargado y el objeto de carrito ya no existe. Esto se debe a que el correo electrónico de carrito abandonado omite la tienda online.

Métodos de script que usan el objeto de carrito

Método	Tipo de retorno	Descripción
.customer	Cliente	Devuelve el titular del carrito (si existe).
.shipping_address	Dirección de envío	Devuelve la dirección de envío del titular del carrito (si existe).
.discount_code	varía	Devuelve: nil si el carrito no tiene código de descuento CartDiscount::FixedAmount si el carrito tiene un descuento de importe fijo CartDiscount::Percentage si el carrito tiene un descuento porcentual CartDiscount::Shipping si el carrito tiene un descuento de envío Devuelve un único código de descuento (consulta Limitaciones) discount_code está presente si se aplicó un descuento al carrito. Esto no significa necesariamente que el precio del carrito cambie. Por ejemplo, si un descuento aplica a carritos superiores a 50 USD y un script reduce el precio del carrito por debajo de 50 USD, discount_code sigue presente, pero el precio del carrito no 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

Métodos de script que usan el objeto CartDiscount::FixedAmount

Método	Tipo de retorno	Descripción
.code	Cadena	Devuelve el código de descuento usado para aplicar el descuento.
.amount	Money	Devuelve el importe del descuento.
.reject({ message: String })	nil	Rechaza el código de descuento aplicado al carrito. Se requiere un message.
.rejected?	Booleano	Indica si se rechazó el código de descuento.

CartDiscount::Percentage

Métodos de script que usan el objeto CartDiscount::Percentage

Método	Tipo de retorno	Descripción
.code	Cadena	Devuelve el código de descuento usado para aplicar el descuento.
.percentage	Decimal	Devuelve el porcentaje del descuento.
.reject({ message: String })	nil	Rechaza el código de descuento aplicado al carrito. Se requiere un message.
.rejected?	Booleano	Indica si se rechazó el código de descuento.

CartDiscount::Shipping

Métodos de script que usan el objeto CartDiscount::Shipping

Método	Tipo de retorno	Descripción
.code	Cadena	Devuelve el código de descuento usado para aplicar el descuento.
.reject({ message: String })	nil	Rechaza el código de descuento aplicado al carrito. Se requiere un message.
.rejected?	Booleano	Indica si se rechazó el código de descuento.

Customer

Métodos de script que usan el objeto Customer

Método	Tipo de retorno	Descripción
.id	entero	Devuelve el número de identificación del cliente.
.email	Cadena	Devuelve la dirección de correo electrónico del cliente.
.tags	List<Etiqueta>	Devuelve una lista de cadenas que representan las etiquetas definidas para un cliente.
.orders_count	entero	Devuelve el número total de pedidos que ha realizado un cliente.
.total_spent	Money	Devuelve el importe total que el cliente ha gastado en todos los pedidos.
.accepts_marketing?	Booleano	Devuelve si el cliente acepta recibir comunicaciones de marketing.

LineItem

Métodos de script que usan el objeto LineItem

Método	Tipo de retorno	Descripción
.grams	grams	Devuelve el peso total de la línea de artículo.
.line_price	Money	El precio de la línea de artículo.
.discounted?	Booleano	Devuelve si el precio de una línea de artículo se ha descontado mediante un script o con un descuento aplicado manualmente. El uso de códigos de descuento no afecta el valor devuelto.
.properties	hash	Devuelve las propiedades especificadas para esta línea de artículo.
.variant	Variant	Devuelve la variante de producto específica que representa esta línea de artículo.
.quantity	entero	Devuelve la cantidad de esta línea de artículo.
.selling_plan_id	entero	Devuelve la identificación del plan de venta de la línea de artículo. Este método es útil cuando la tienda vende suscripciones y quieres que el script detecte cuándo una variante de producto se sold as a subscription.

List

Métodos de script que usan el objeto List

Método	Tipo de retorno	Descripción
.new	List	Crea un objeto nuevo para representar una lista.
.[]	elemento o nil	Devuelve el elemento en el índice especificado.
.&	List	Devuelve una lista nueva con los elementos comunes a las dos listas, sin duplicados.
.delete_if	List	Elimina elementos usando un bloque de código opcional. Consulta la documentación de Ruby's delete_if method.
.empty?	Booleano	Devuelve true si la lista no contiene elementos.
.first	elemento o nil	Devuelve el primer elemento o nil si la lista está vacía.
.index(*args, &block)	int o nil	Devuelve el índice del primer elemento de la lista. Si se indica un bloque en lugar de un argumento, devuelve el índice del primer elemento para el que el bloque sea verdadero.
.rindex(*args, &block)	int o nil	Devuelve el índice del último elemento de la lista. Si se indica un bloque en lugar de un argumento, devuelve el índice del primer elemento para el que el bloque sea verdadero.
.last	elemento o nil	Devuelve el último elemento o nil si la lista está vacía.
.length	int	Devuelve la cantidad de elementos de la lista.
.size	int	Alias de length.
.each(*args, &block)	List	Llama a un bloque una vez por cada elemento de la lista y pasa el elemento como parámetro al bloque.

ShippingAddress

Métodos de script que usan el objeto ShippingAddress

Método	Tipo de retorno	Descripción
.name	cadena	Devuelve el nombre de la persona asociada a la dirección de envío.
.address1	cadena	Devuelve la primera línea de la dirección de envío.
.address2	cadena	Devuelve la segunda línea opcional de la dirección de envío.
.phone	cadena	Devuelve el número de teléfono de la dirección de envío.
.city	cadena	Devuelve la ciudad de la dirección de envío.
.zip	cadena	Devuelve el código postal de la dirección de envío.
.province	cadena	Devuelve la provincia o el estado de la dirección de envío.
.province_code	cadena	Devuelve la abreviatura de la provincia o el estado de la dirección de envío.
.country_code	cadena	Devuelve la abreviatura del país de la dirección de envío.

Money

Métodos de script que usan el objeto Money

Método	Tipo de retorno	Descripción
.derived_from_presentment(customer_cents:X)	Money	Convierte un importe (en centavos) de la moneda local del cliente (de presentación) a la moneda de la tienda. Este método acepta el parámetro customer_cents, que admite un número en centavos. Por ejemplo, Money.derived_from_presentment(customer_cents: 500).
.new	Money	Crea un objeto nuevo para representar un precio.
.zero	Money	Crea un objeto nuevo con un precio de cero.
+	Money	Suma dos objetos Money.
-	Money	Resta un objeto Money de otro.
*	Money	Multiplica un objeto Money por un número.

Ejemplos de Money

Money.new(cents: 1000)

Crea un objeto Money que representa 1.000 centavos, o 10 USD.

Money.new(cents: 100) * 50

Crea un objeto Money que representa 1 USD y luego multiplica ese importe por 50. Devuelve un objeto Money que representa 50 USD.

Variant

Métodos de script que usan el objeto Variant

Método	Tipo de retorno	Descripción
.id	entero	Devuelve el número de identificación de la variante.
.price	Money	Devuelve el precio unitario de la variante.
.product	Product	Devuelve el producto asociado a la variante.
.skus	List<String>	Devuelve los códigos de artículo (SKU) de la variante, que suelen usarse para rastrear el inventario.
.title	Cadena	Devuelve el título de la variante.

Product

Métodos de script que usan el objeto Product

Método	Tipo de retorno	Descripción
.id	entero	Devuelve el número de identificación del producto.
.gift_card?	Booleano	Devuelve si el producto es una tarjeta de regalo.
.tags	List<Etiqueta>	Devuelve una lista de cadenas que representan las etiquetas configuradas para este producto.
.product_type	Cadena	Una clasificación con la que se puede etiquetar un producto, que se usa comúnmente para filtrar y buscar.
.vendor	Cadena	Devuelve el proveedor de este producto.

Kernel

Kernel es un módulo de Ruby que se incluye en todas las clases. Por eso, sus métodos están disponibles para todos los objetos. Estos métodos funcionan de la misma manera que las funciones globales en otros lenguajes.

Métodos de script que usan el objeto Kernel

Método	Tipo de retorno	Descripción
.exit	ninguno	Finaliza la ejecución del script actual sin errores. Si se ejecuta antes de asignar algo a Output.cart, el script no tiene efecto. Es una forma útil de salir de los scripts, por ejemplo, si el cliente no cumple los requisitos para ejecutar el script.

Ejemplo 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 para líneas de artículo

Los siguientes métodos solo se pueden usar en scripts de líneas de artículo:

Carrito

Métodos de script que usan el objeto Cart en scripts de líneas de artículo

Método	Tipo de retorno	Descripción
.subtotal_price_was	Money	Devuelve el subtotal del carrito antes de aplicar descuentos.
.subtotal_price_changed?	Booleano	Devuelve si el subtotal ha cambiado.

LineItem

Métodos de script que usan el objeto LineItem en scripts de líneas de artículo

Método	Tipo de retorno	Descripción
.change_line_price(Money new_price, { message: String })	Money	Cambia el precio de la línea de artículo al importe especificado. El parámetro message es obligatorio. new_price debe ser menor que el precio actual.
.original_line_price	Money	Devuelve el precio original de la línea de artículo antes de aplicar scripts y descuentos.
.line_price_was	Money	Devuelve el precio de la línea de artículo antes de los cambios aplicados por el script actual.
.line_price_changed?	Booleano	Devuelve si el precio de la línea de artículo ha cambiado.
.change_properties(hash new_properties, { message: String })	hash	Establece propiedades nuevas para una línea de artículo. El hash de propiedades original se guarda en properties_was y el hash de propiedades que se pasa al método se convierte en las nuevas propiedades de la línea de artículo.
.properties_was	hash	Devuelve el hash de propiedades original de la línea de artículo antes de aplicar cualquier cambio.
.properties_changed?	Booleano	Devuelve si las propiedades de la línea de artículo han cambiado.
.split({ take: Integer })	LineItem	Divide una línea de artículo en dos líneas de artículo. take especifica la cantidad que se quitará de la línea de artículo original para crear la nueva línea de artículo.

Ejemplo de .split

Este script de ejemplo divide una línea de artículo llamada original_line_item en dos líneas de artículo. La nueva línea de artículo tiene una cantidad de 1 (especificada por take: 1). Luego, el script aplica un precio con descuento a la nueva línea de artículo con el mensaje "Tercer sombrero por 5 dólares".

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 que usan el objeto Variant en scripts de líneas de artículo

Método	Tipo de retorno	Descripción
.compare_at_price	Money	Devuelve el precio de comparación de la variante. Devuelve nil si la variante no tiene precio de comparación.

Métodos de envío

Los siguientes métodos se pueden usar en scripts de envío:

Entrada

Métodos de script que usan el objeto Input en scripts de envío

Método	Tipo de retorno	Descripción
.shipping_rates	ShippingRateList	Devuelve una lista de todas las tarifas de envío.

ShippingRateList

Métodos de script que usan el objeto ShippingRateList en scripts de envío

Método	Tipo de retorno	Descripción
.delete_if	ShippingRateList	Elimina tarifas de envío con un bloque de código opcional. Consulta la documentación de Ruby's delete_if method.
.sort!	ShippingRateList	Ordena las tarifas de envío con el operador de comparación o con un bloque de código opcional. Consulta la documentación de Ruby's sort! method.
.sort_by!	ShippingRateList	Ordena las tarifas de envío con un bloque de código opcional. Consulta la documentación de Ruby's sort_by! method.

ShippingRate

Métodos de script que usan el objeto ShippingRate en scripts de envío

Método	Tipo de retorno	Descripción
.code	Cadena	Devuelve el código de la tarifa de envío.
.markup	Money	Devuelve el recargo de una tarifa de envío, si corresponde.
.name	Cadena	Devuelve el nombre de la tarifa de envío. Se puede modificar con el método change_name.
.price	Money	Devuelve el precio de la tarifa de envío.
.source	Cadena	Devuelve el origen (la empresa de transporte) asociado a la tarifa de envío, si corresponde. No se puede modificar.
.change_name(String new_name)	Cadena	Cambia el nombre (máximo 255 caracteres) de la tarifa de envío. No es posible cambiar, eliminar ni ocultar el origen.
.apply_discount(Money discount, { message: String })	Money	Aplica un descuento por el monto fijo especificado. El precio no puede quedar por debajo de 0. Se requiere un mensaje.
.phone_required?	Booleano	Devuelve true si se requiere un número de teléfono para obtener la tarifa de envío, o false si no se requiere.

Métodos de pago

Estos métodos se pueden usar en scripts de pago:

Entrada

Métodos de script que usan el objeto Input en scripts de pago

Método	Tipo de retorno	Descripción
.payment_gateways	PaymentGatewaysList	Devuelve una lista de todas las pasarelas de pago de la tienda.

PaymentGatewayList

Métodos de script que usan el objeto PaymentGatewayList en scripts de pago

Método	Tipo de retorno	Descripción
.delete_if	PaymentGatewayList	Elimina pasarelas de pago con un bloque de código opcional. Consulta la documentación de Ruby's delete_if method.
.sort!	PaymentGatewayList	Ordena las pasarelas de pago con el operador de comparación o con un bloque de código opcional. Consulta la documentación de Ruby's sort! method.
.sort_by!	PaymentGatewayList	Ordena las pasarelas de pago con un bloque de código opcional. Consulta la documentación de Ruby's sort_by! method.

PaymentGateway

Método	Tipo de retorno	Descripción
.name	Cadena	Devuelve el nombre de la pasarela de pago.
.enabled_card_brands	List<String>	Si la pasarela de pago admite tarjetas de crédito, devuelve una lista de los tipos de tarjeta de crédito que acepta la tienda. Si la pasarela no admite tarjetas de crédito, devuelve una lista vacía.
.change_name(String new_name)	Cadena	Cambia el nombre de la pasarela de pago. No se pueden cambiar de nombre las pasarelas de pago con logo.

Ejemplos

En el siguiente ejemplo de script de línea de artículo, cuando un cliente compra un producto que no es una tarjeta de regalo, el precio del producto se reduce en 9 USD. Además, se muestra el monto total que el cliente ha gastado en todas las visitas a la tienda:

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ás información

Más información sobre:

• The basics of Ruby
• Creating scripts
• Testing and debugging your scripts
• Updating your Liquid templates for scripts
• Shopify Scripts