Referencia API de Shopify Scripts

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

Hay diferentes tipos de script. Se asigna un tipo de script cuando creas el script en la aplicación Script Editor, según la plantilla de script que elijas para comenzar:

Scripts de línea de artículo

Los scripts de línea de artículo afectan a las líneas de artículo que contiene un carrito y pueden cambiar los precios y hacer descuentos. Estos scripts se ejecutan cuando se realiza un cambio en el carrito.

Los scripts de línea de artículo que descuentan una suscripción se aplican solo al primer pago de la suscripción. El script no descuenta los pagos posteriores.

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

Scripts de envío

Los scripts de envío interactúan con el envío y pueden cambiar los métodos de envío y otorgar descuentos sobre 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. El script no descuenta los pagos posteriores.

Algunos métodos solo se pueden usar en los scripts de envío.

Scripts de pago

Los scripts de pago interactúan con los pagos y pueden cambiar el nombre de las pasarelas de pago, ocultarlas y reordenarlas. 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 los scripts de pago.

En esta página

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 resultado	Descripción
.cart	Carrito	Muestra un objeto de carrito que se puede cambiar.
.locale	cadena	Muestra la configuración regional del cliente. Por ejemplo, `en` , `fr` , o `pt-BR`.

Carrito

El objeto del carrito solo está disponible en la tienda online. Algunos carritos abandonados tienen acceso al objeto del carrito. No obstante, si se cerró una pantalla de pago y luego el cliente visita el carrito abandonado, el script enviará al cliente directamente a la pantalla de pago rellenada y sin el objeto del carrito. Esto se debe a que la página principal de la tienda ha sido omitida por el correo electrónico de carrito abandonado.

Métodos de script usando el objeto Cart
Método	Tipo de resultado	Descripción
.customer	Cliente	Muestra al propietario del carrito (si existe).
.shipping_address	Dirección de envío	Muestra la dirección de envío del propietario del carrito (si existe).
.discount_code	varía	Muestra lo siguiente: `nil` si el carrito no tiene código de descuento. `CartDiscount::FixedAmount` si el carrito tiene un monto fijo de descuento. `CartDiscount::Percentage` si el carrito tiene un descuento por porcentaje. `CartDiscount::Shipping` si el carrito tiene un descuento de envío. Muestra un solo código de descuento (ver Limitaciones) `discount_code` estará presente si se ha aplicado un descuento al carrito. Esto no significa necesariamente que el precio del carrito cambia. Por ejemplo, si un descuento se aplica a carritos superiores a $50, y un script reduce el precio del carrito a menos de $50, `discount_code` todavía está presente, pero el precio del carrito no cambia. Ve un ejemplo de `discount_code`.
.line_items	Lista<LineItem>	Muestra una lista que contiene las líneas de artículo en el carrito.
.presentment_currency	Lista<String>	Devuelve la moneda local (de presentación) del cliente (en formato ISO 4217). Por ejemplo, USD.
.subtotal_price	Dinero	Muestra el precio del subtotal del carrito después de aplicar los descuentos de línea de artículo pero antes de aplicar los códigos de descuento.
.total_weight	Gramos	Muestra el peso total de todas las líneas de artículo en el carrito.

CartDiscount::FixedAmount

Métodos de script usando el objeto CartDiscount::FixedAmount
Método	Tipo de resultado	Descripción
.code	Cadena	Muestra el código de descuento que se usó para aplicar el descuento.
.amount	Dinero	Muestra el importe del descuento.
.reject({ message: String })	nulo	Rechaza el código de descuento aplicado al carrito. Un `mensaje` es obligatorio.
.rejected?	Booleano	Muestra si se rechazó el código de descuento.

CartDiscount::Percentage

Métodos de script usando el objeto CartDiscount::Percentage
Método	Tipo de resultado	Descripción
.code	Cadena	Muestra el código de descuento que se usó para aplicar el descuento.
.percentage	Decimal	Muestra el porcentaje del descuento.
.reject({ message: String })	nulo	Rechaza el código de descuento aplicado al carrito. Un `mensaje` es obligatorio.
.rejected?	Booleano	Muestra si se rechazó el código de descuento.

CartDiscount::Shipping

Métodos de script usando el objeto CartDiscount::Shipping
Método	Tipo de resultado	Descripción
.code	Cadena	Muestra el código de descuento que se usó para aplicar el descuento.
.reject({ message: String })	nulo	Rechaza el código de descuento aplicado al carrito. Un `mensaje` es obligatorio.
.rejected?	Booleano	Muestra si se rechazó el código de descuento.

Cliente

Métodos de script usando el objeto Customer
Método	Tipo de resultado	Descripción
.id	Número entero	Muestra el número de identificación del cliente.
.email	Cadena	Muestra la dirección de correo electrónico del cliente.
.tags	Lista<Tag>	Muestra una lista de cadenas que representan cualquier conjunto de etiquetas para un cliente.
.orders_count	Número entero	Muestra el número total de pedidos que realizó un cliente.
.total_spent	Dinero	Muestra el importe total que el cliente gastó en todos los pedidos.
.accepts_marketing?	Booleano	Muestra si el cliente acepta material publicitario.

LineItem

<tdgrams

Métodos de script usando el objeto LineItem
Método	Tipo de resultado	Descripción
.grams	Muestra el peso total de la línea de artículo.
.line_price	Dinero	El precio de una línea de artículo.
.discounted?	Booleano	Muestra si un script o un descuento aplicado manualmente ha descontado el precio de una línea de artículo. El uso de códigos de descuento no afecta al valor de devolución.
.properties	hash	Muestra las propiedades que se especificaron para esta línea de artículos.
.variant	Variante	Muestra la variante específica del producto representada por la línea de artículo.
.quantity	Número entero	Muestra la cantidad de esta línea de artículo.
.selling_plan_id	Número entero	Devuelve el identificador del plan de ventas de la línea de artículo. Este método es útil cuando la tienda vende suscripciones y deseas que el script detecte cuando una variante de producto se vende como suscripción.

Lista

Métodos de script usando el objeto List
Método	Tipo de resultado	Descripción
.new	Lista	Crea un nuevo objeto para representar una lista.
.[]	Elemento o nulo	Muestra el elemento en el índice especificado.
.&	Lista	Muestra una nueva lista que contiene elementos comunes a las dos listas, sin duplicados.
.delete_if	Lista	Elimina elementos usando un bloque de código opcional. Consulta la documentación del método `delete_if` de Ruby.
.empty?	Booleano	Muestra `verdadero` si la lista no contiene elementos.
.first	Elemento o nulo	Muestra el primer elemento o `nulo` si la lista está vacía.
.index(*args, &block)	int. o nulo	Muestra el índice del primer elemento de la lista. Si se da un bloque en lugar de un argumento, muestra el índice del primer elemento para el que el bloque es verdadero.
.index(*args, &block)	int. o nulo	Muestra el índice del último elemento de la lista. Si se da un bloque en lugar de un argumento, muestra el índice del primer elemento para el que el bloque es verdadero.
.last	Elemento o nulo	Muestra el último elemento o `nulo` si la lista está vacía.
.length	int.	Muestra la cantidad de elementos de la lista.
.size	int.	Alias para longitud.
.each(*args, &block)	Lista	Llama a un bloque una vez por cada elemento de la lista, pasando el elemento como un parámetro al bloque.

Dirección de envío

Métodos de script usando el objeto ShippingAddress
Método	Tipo de resultado	Descripción
.name	string	Muestra el nombre de la persona asociada a la dirección de envío.
.address1	string	Muestra la parte de la dirección postal en la dirección de envío.
.address2	string	Muestra el campo adicional opcional de la parte de la dirección postal en la dirección de envío.
.phone	string	Muestra el número de teléfono de la dirección de envío.
.city	string	Muestra la ciudad de la dirección de envío.
.zip	string	Muestra el código postal de la dirección de envío.
.provincia	string	Muestra la provincia o el estado de la dirección de envío.
.province_code	string	Muestra el valor abreviado de la provincia o el estado de la dirección de envío.
.country_code	string	Muestra el valor abreviado del país de la dirección de envío.

Dinero

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

Ejemplos de dinero

Money.new(cents: 1000)

Crea un objeto Money que representa 1000 centavos o $10.

Money.new(cents: 100) * 50

Crea un objeto Money que representa $1 y multiplica esa cantidad por 50. Muestra un objeto Money que representa $50.

Variante

Métodos de script usando el objeto Variant
Método	Tipo de resultado	Descripción
.id	Número entero	Muestra el número de id. de la variante.
.price	Dinero	Muestra el precio unitario de la variante.
.product	Producto	Muestra el producto asociado de la variante.
.skus	Lista<String>	Muestra los códigos de artículos (SKU) de la variante, que a menudo se usan para hacer un seguimiento del inventario.
.title	Cadena	Muestra el título de la variante.

Producto

Métodos de script usando el objeto Product
Método	Tipo de resultado	Descripción
.id	Número entero	Muestra el número de identificación del producto.
.gift_card?	Booleano	Muestra si el producto es una tarjeta de regalo o no.
.tags	Lista<Tag>	Muestra una lista de cadenas que representan las etiquetas establecidas para este producto.
.product_type	Cadena	Una categorización con la que se puede etiquetar un producto, que se suele usar para filtrar y buscar.
.vendor	Cadena	Muestra el proveedor de este producto.

Kernel

Kernel es un módulo de Ruby que se incluye en cada clase. Por lo tanto, sus métodos están disponibles para todos los objetos. Estos métodos actúan de la misma manera que lo hacen las funciones globales en otros idiomas.

Métodos de script usando el objeto Kernel
Método	Tipo de resultado	Descripción
.exit	ninguno	Finaliza la ejecución del script actual sin errores. Si este se ejecuta antes de asignar algo a `Output.cart`, el script no tiene efecto. Esta es una forma útil de salir de los scripts, por ejemplo, si el cliente no es elegible 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 de línea de artículo

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

Carrito

Métodos de script usando el objeto Cart en los scripts de línea de artículo
Método	Tipo de resultado	Descripción
.subtotal_price_was	Dinero	Muestra el precio del subtotal del carrito antes de aplicar cualquier descuento.
.subtotal_price_changed?	Booleano	Muestra si el precio del subtotal ha cambiado.

LineItem

Métodos de script usando el objeto LineItem en los scripts de línea de artículo
Método	Tipo de resultado	Descripción
.change_line_price(Money new_price, { message: String })	Dinero	Cambia el precio de la línea de artículo a la cantidad especificada. Un `mensaje` es obligatorio. `new_price` debe ser inferior al precio actual.
.original_line_price	Dinero	Muestra el precio original de la línea de artículo antes de aplicar los scripts y los descuentos.
.line_price_was	Dinero	Muestra el precio de la línea de artículo antes de que el script actual aplique los cambios.
.line_price_changed?	Booleano	Muestra si el precio de la línea de artículo ha cambiado.
.change_properties(hash new_properties, { message: String })	hash	Establece nuevas propiedades para una línea de artículo. El hash original de propiedades se almacena en `properties_was` y el hash de propiedades que se pasa al método se convierte en las nuevas propiedades para la línea de artículo.
.properties_was	hash	Muestra el hash de propiedades originales de la línea de artículo antes de que se aplicaran los cambios.
.properties_changed?	Booleano	Muestra si se han cambiado las propiedades de la línea de artículo.
.split({ take: Integer })	LineItem	Divide una línea de artículo en dos líneas de artículo. `take` especifica qué cantidad eliminar 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ículos. 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

Variante

Métodos de script usando el objeto Variant en los scripts de línea de artículo
Método	Tipo de resultado	Descripción
.compare_at_price	Dinero	Muestra el precio de comparación de la variante. Muestra `nula` si la variante no tiene un precio de comparación.

Métodos de envío

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

Entrada

Métodos de script usando el objeto Input en los scripts de envío
Método	Tipo de resultado	Descripción
.shipping_rates	ShippingRateList	Muestra una lista de todas las tarifas de envío.

ShippingRateList

Métodos de script usando el objeto ShippingRateList en los scripts de envío
Método	Tipo de resultado	Descripción
.delete_if	ShippingRateList	Elimina las tarifas de envío usando un bloque de código opcional. Consulta la documentación del método `delete_if` de Ruby.
.sort!	ShippingRateList	Ordena las tarifas de envío utilizando el operador de comparación o un bloque de código opcional. Consulta la documentación del método `sort!` de Ruby.
.sort_by!	ShippingRateList	Ordena las tarifas de envío utilizando un bloque de código opcional. Consulta la documentación del método `sort_by!` de Ruby.

ShippingRate

Métodos de script usando el objeto ShippingRate en los scripts de envío
Método	Tipo de resultado	Descripción
.code	Cadena	Muestra el código de la tarifa de envío.
.markup	Dinero	Devuelve el margen de una tarifa de envío, si corresponde.
.name	Cadena	Muestra el nombre de la tarifa de envío. Se puede modificar mediante el método `change_name`.
.price	Dinero	Muestra el precio de la tarifa de envío.
.source	Cadena	Muestra la fuente (la empresa de transporte) asociada a la tarifa de envío, si procede. No se puede modificar.
.change_name(String new_name)	Cadena	Cambia el nombre (máximo de 255 caracteres) de la tarifa de envío. No es posible cambiar, eliminar ni ocultar la fuente.
.apply_discount(Money discount, { message: String })	Dinero	Aplica un descuento de la cantidad fija especificada. El precio no se puede reducir a menos de 0. Es obligatorio un mensaje.
.phone_required?	Booleano	indica que es `verdadero` si se requiere un número de teléfono para obtener la tarifa de envío o `falso` si no se requiere un número de teléfono.

Métodos de pago

Los siguientes métodos se pueden usar en los scritps de pago:

Entrada

Métodos de script usando el objeto Input en los scripts de pago
Método	Tipo de resultado	Descripción
.payment_gateways	PaymentGatewaysList	Muestra una lista de todas las pasarelas de pago en la tienda.

PaymentGatewayList

Métodos de script usando el objeto PaymentGatewayList en los scripts de pago
Método	Tipo de resultado	Descripción
.delete_if	PaymentGatewayList	Elimina las pasarelas de pago usando un bloque de código opcional. Consulta la documentación del método `delete_if` de Ruby.
.sort!	PaymentGatewayList	Ordena las pasarelas de pago usando el operador de comparación o un bloque de código opcional. Consulta la documentación del método `sort!` de Ruby.
.sort_by!	PaymentGatewayList	Ordena las pasarelas de pago usando un bloque de código opcional. Consulta la documentación del método `sort_by!` de Ruby.

PaymentGateway

Método	Tipo de resultado	Descripción
.name	Cadena	Muestra el nombre de la pasarela de pago.
.enabled_card_brands	Lista<String>	Si la pasarela de pago admite tarjetas de crédito, muestra una lista de los tipos de tarjetas de crédito que se aceptan en la tienda. Si la pasarela no admite tarjetas de crédito, muestra una lista vacía.
.change_name(String new_name)	Cadena	Cambia el nombre de la pasarela de pago. No se puede cambiar el nombre de las pasarelas de pago con logos.

Ejemplos

En el siguiente ejemplo de script de línea de artículo, cuando un cliente pide un producto que no es una tarjeta de regalo, el precio del producto tiene un descuento de $9. Además, se muestra la cantidad total que el cliente ha gastado en todas las visitas a tu 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

Leer más

Leer más acerca de