Referencia API de Shopify Scripts

Esta página fue impresa el Oct 21, 2023. 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étodossolo se pueden usar en los scripts de línea de artículo.

Scripts de envío

Los scripts de envío interactúan con elenvíoy 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étodossolo se pueden usar en los scripts de envío.

Scripts de pago

Los scripts de pago interactúan con lospagosy 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étodossolo 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, opt-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_codeestará 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_codetodavía está presente, pero el precio del carrito no cambia.

Ve un ejemplo dediscount_code.
.line_items Lista Muestra una lista que contiene las líneas de artículo en el carrito.
.presentment_currency Lista Devuelve la moneda local (de presentación) del cliente (en formatoISO 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. Unmensajees 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. Unmensajees 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. Unmensajees 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 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

grams Muestra el peso total de la línea de artículo.
Métodos de script usando el objeto LineItem
Método Tipo de resultado Descripción
.grams
.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 变体 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 productose 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联合国bloque de鳕鱼igo opcional. Consulta la documentación delmétododelete_ifde Ruby.
.empty? Booleano

Muestraverdaderosi la lista no contiene elementos.
.first Elemento o nulo

Muestra el primer elemento onulosi 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 onulosi 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 具体la provincia oel 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ámetrocustomer_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 deDinero.
- Dinero Resta un objeto dedinerode otro.
* Dinero Multiplica un objeto deDineropor un número.

Ejemplos de dinero

Money.new(cents:1000)

Crea un objetoMoneyque representa 1000 centavos o $10.

Money.new(cents:100)*50

Crea un objetoMoneyque representa $1 y multiplica esa cantidad por 50. Muestra un objetoMoneyque representa $50.

变体

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 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 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

Kerneles 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 aOutput.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.customerifcustomer&&customer.email.end_with?("@mycompany.com")# Employees are not eligible for this promotion.exitend

Métodos de línea de artículo

Los siguientes métodos solo se pueden usar en losscripts 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(Moneynew_price, { message:String}) Dinero Cambia el precio de la línea de artículo a la cantidad especificada. Unmensajees obligatorio.new_pricedebe 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(hashnew_properties, { message:String}) hash Establece nuevas propiedades para una línea de artículo. El hash original de propiedades se almacena enproperties_wasy 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.takeespecifica 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 llamadaoriginal_line_itemen dos líneas de artículos. La nueva línea de artículo tiene una cantidad de 1 (especificada por花: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".

iforiginal_line_item.quantity>=3new_line_item=original_line_item.split(花:1)new_line_item.change_line_price(Money.new(cents:500),message:"Third hat for 5 dollars")cart.line_items<<new_line_itemend

变体

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. Muestranulasi la variante no tiene un precio de comparación.

Métodos de envío

Los siguientes métodos se pueden utilizar en losscripts 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étododelete_ifdeRuby.
.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 delmétodosort!de Ruby.
.sort_by! ShippingRateList Ordena las tarifas de envío utilizando un bloque de código opcional. Consulta la documentación delmétodosort_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étodochange_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(Stringnew_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(Moneydiscount, { 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 esverdaderosi se requiere un número de teléfono para obtener la tarifa de envío ofalsosi no se requiere un número de teléfono.

Métodos de pago

Los siguientes métodos se pueden usar en losscritps 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étododelete_ifdeRuby.
.sort! PaymentGatewayList Ordena las pasarelas de pago usando el operador de comparación o un bloque de código opcional. Consulta la documentación delmétodosort!de Ruby.
.sort_by! PaymentGatewayList Ordena las pasarelas de pago usando un bloque de código opcional. Consulta la documentación delmétodosort_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

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(Stringnew_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