Referencia API de Shopify Scripts

Esta página fue impresa el Apr 26, 2024. Para acceder a la versión actual, por favor visita https://help.shopify.com/es/manual/checkout-settings/script-editor/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:

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

¿Estás listo/a para comenzar a vender con Shopify?

Prueba gratis