Referência da API de Scripts da Shopify

Os scripts são escritos com uma API do Ruby que oferece muito controle e flexibilidade.

Requisito de plano

Os Scripts da Shopify foram descontinuados em 30 de junho de 2026. Todos os scripts que ainda estavam publicados na loja foram desativados e não funcionam mais. Para recriar essas personalizações, faça a transição para o Shopify Functions. Saiba mais sobre como migrar dos Scripts da Shopify para o Shopify Functions.

Existem diferentes tipos de script. Um tipo é atribuído ao script quando ele é criado no app Script Editor, com base no modelo de script que você escolheu para começar:

Scripts de item de linha

Os scripts de item de linha afetam os itens de linha no carrinho e podem alterar preços e conceder descontos. Esses scripts são executados sempre que uma alteração é feita no carrinho.

Scripts de item de linha que dão desconto em uma assinatura se aplicam apenas ao primeiro pagamento dela. Os pagamentos subsequentes não recebem o desconto do script.

Alguns métodos só podem ser usados em scripts de item de linha.

Scripts de frete

Os scripts de frete interagem com o frete e podem alterar as formas de frete e conceder descontos nas taxas de frete. Esses scripts são executados quando o checkout chega à página de opções de frete.

Scripts de frete que dão desconto na taxa de frete de uma assinatura se aplicam apenas ao primeiro pagamento dela. Os pagamentos subsequentes não recebem o desconto do script.

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

Scripts de pagamento

Os scripts de pagamento interagem com pagamentos e podem renomear, ocultar e reordenar gateways de pagamento. Vale lembrar que eles não interagem com gateways de pagamento exibidos antes da tela de checkout, como o Apple Pay. Esses scripts são executados quando o checkout chega à página de pagamento.

Alguns métodos só podem ser usados em scripts de pagamento.

Métodos gerais

Os métodos a seguir podem ser usados em qualquer tipo de script:

Entrada

Métodos de entrada de script

Método	Tipo de retorno	Descrição
.cart	Cart	Retorna um objeto de carrinho mutável.
.locale	string	Retorna a localidade do cliente. Por exemplo: en, fr ou pt-BR.

Cart

O objeto do carrinho está disponível apenas na loja virtual. Alguns checkouts abandonados têm acesso ao objeto do carrinho. No entanto, se um checkout for fechado e um cliente visitar o checkout abandonado, ele será direcionado para o checkout pré-preenchido, e o objeto do carrinho não existirá mais. Isso ocorre porque a vitrine virtual foi ignorada pelo e-mail de checkout abandonado.

Métodos de script que usam o objeto Cart

Método	Tipo de retorno	Descrição
.customer	Customer	Retorna o proprietário do carrinho (se houver).
.shipping_address	ShippingAddress	Retorna o endereço de entrega do proprietário do carrinho (se houver).
.discount_code	varia	Retorna: nil se o carrinho não tiver um código de desconto CartDiscount::FixedAmount se o carrinho tiver um desconto de valor fixo CartDiscount::Percentage se o carrinho tiver um desconto de percentual CartDiscount::Shipping se o carrinho tiver um desconto de frete Retorna um único código de desconto (consulte Limitações) discount_code estará presente se um desconto tiver sido aplicado ao carrinho, mas isso não significa necessariamente que o preço do carrinho mudará. Por exemplo, se um desconto se aplicar a carrinhos acima de US$ 50 e um script reduzir o preço do carrinho para menos de US$ 50, o discount_code ainda estará presente, mas o preço do carrinho não mudará. <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 usam o objeto CartDiscount::FixedAmount

Método	Tipo de retorno	Descrição
.code	String	Retorna o código de desconto usado para aplicar o desconto.
.amount	Money	Retorna o valor do desconto.
.reject({ message: String })	nil	Recusa o código de desconto aplicado ao carrinho. Uma message é obrigatória.
.rejected?	Booleano	Retorna se o código de desconto foi recusado.

CartDiscount::Percentage

Métodos de script que usam o objeto CartDiscount::Percentage

Método	Tipo de retorno	Descrição
.code	String	Retorna o código de desconto usado para aplicar o desconto.
.percentage	Decimal	Retorna o valor percentual do desconto.
.reject({ message: String })	nil	Recusa o código de desconto aplicado ao carrinho. Uma message é obrigatória.
.rejected?	Booleano	Retorna se o código de desconto foi recusado.

CartDiscount::Shipping

Métodos de script que usam o objeto CartDiscount::Shipping

Método	Tipo de retorno	Descrição
.code	String	Retorna o código de desconto usado para aplicar o desconto.
.reject({ message: String })	nil	Recusa o código de desconto aplicado ao carrinho. Uma message é obrigatória.
.rejected?	Booleano	Retorna se o código de desconto foi recusado.

Cliente

Métodos de script que usam o objeto Cliente

Método	Tipo de retorno	Descrição
.id	Inteiro	Retorna o número de ID do cliente.
.email	String	Retorna o endereço de e-mail do cliente.
.tags	Lista<Tag>	Retorna uma lista de strings que representam quaisquer tags definidas para um cliente.
.orders_count	Inteiro	Retorna o número total de pedidos que um cliente fez.
.total_spent	Money	Retorna o valor total que o cliente gastou em todos os pedidos.
.accepts_marketing?	Booleano	Retorna se o cliente aceita marketing.

Item de linha

Métodos de script que usam o objeto Item de linha

Método	Tipo de retorno	Descrição
.grams	gramas	Retorna o peso total do item de linha.
.line_price	Money	O preço do item de linha.
.discounted?	Booleano	Retorna se o preço de um item de linha foi descontado por um script ou por um desconto aplicado manualmente. O uso de códigos de desconto não afeta o valor de retorno.
.properties	hash	Retorna as propriedades que foram especificadas para este item de linha.
.variant	Variante	Retorna a variante do produto específica representada pelo item de linha.
.quantity	Inteiro	Retorna a quantidade deste item de linha.
.selling_plan_id	Inteiro	Retorna o ID do plano de venda do item de linha. Esse método é útil quando a loja vende assinaturas e você quer que o script detecte quando uma variante de produto é vendida como uma assinatura.

Lista

Métodos de script que usam o objeto Lista

Método	Tipo de retorno	Descrição
.new	Lista	Cria um novo objeto para representar uma lista.
.[]	Elemento ou nil	Retorna o elemento no índice especificado.
.&	Lista	Retorna uma nova lista com os elementos comuns às duas listas, sem duplicatas.
.delete_if	Lista	Exclui elementos usando um bloco de código opcional. Consulte a documentação do método delete_if do Ruby.
.empty?	Booleano	Retorna true se a lista não contiver elementos.
.first	Elemento ou nil	Retorna o primeiro elemento ou nil se a lista estiver vazia.
.index(*args, &block)	int ou nil	Retorna o índice do primeiro elemento da lista. Se um bloco for fornecido em vez de um argumento, retorna o índice do primeiro elemento para o qual o bloco é verdadeiro.
.rindex(*args, &block)	int ou nil	Retorna o índice do último elemento da lista. Se um bloco for fornecido em vez de um argumento, retorna o índice do primeiro elemento para o qual o bloco é verdadeiro.
.last	Elemento ou nil	Retorna o último elemento ou nil se a lista estiver vazia.
.length	int	Retorna o número de elementos na lista.
.size	int	Alias para .length.
.each(*args, &block)	Lista	Chama um bloco uma vez para cada elemento na lista, passando o elemento como um parâmetro para o bloco.

Endereço de entrega

Métodos de script que usam o objeto Endereço de entrega

Método	Tipo de retorno	Descrição
.name	string	Retorna o nome da pessoa associada ao endereço de entrega.
.address1	string	Retorna a parte do endereço referente à rua.
.address2	string	Retorna o campo adicional opcional da parte do endereço referente à rua.
.phone	string	Retorna o número de telefone do endereço de entrega.
.city	string	Retorna a cidade do endereço de entrega.
.zip	string	Retorna o CEP do endereço de entrega.
.province	string	Retorna a província/estado do endereço de entrega.
.province_code	string	Retorna o valor abreviado da província/estado do endereço de entrega.
.country_code	string	Retorna o valor abreviado do país do endereço de entrega.

Dinheiro

Métodos de script que usam o objeto Dinheiro

Método	Tipo de retorno	Descrição
.derived_from_presentment(customer_cents:X)	Money	Converte um valor (em centavos) da moeda local (de apresentação) do cliente para a moeda da loja. Este método aceita o parâmetro customer_cents, que aceita um número em centavos. Por exemplo, Money.derived_from_presentment(customer_cents: 500).
.new	Money	Cria um novo objeto para representar um preço.
.zero	Money	Cria um novo objeto com preço zero.
+	Money	Soma dois objetos Money.
-	Money	Subtrai um objeto Money de outro.
*	Money	Multiplica um objeto Money por um número.

Exemplos de Money

Money.new(cents: 1000)

Cria um objeto Money que representa 1.000 centavos, ou US$ 10.

Money.new(cents: 100) * 50

Cria um objeto Money que representa US$ 1 e o multiplica por 50. Retorna um objeto Money que representa US$ 50.

Variante

Métodos de script que usam o objeto Variant

Método	Tipo de retorno	Descrição
.id	Inteiro	Retorna o número de ID da variante.
.price	Money	Retorna o preço unitário da variante.
.product	Produto	Retorna o produto associado da variante.
.skus	List<String>	Retorna as Unidades de manutenção de estoque (SKUs) da variante, que costumam ser usadas para rastrear o estoque.
.title	String	Retorna o título da variante.

Produto

Métodos de script que usam o objeto Product

Método	Tipo de retorno	Descrição
.id	Inteiro	Retorna o número de ID do produto.
.gift_card?	Booleano	Retorna se o produto é um cartão-presente.
.tags	Lista<Tag>	Retorna uma lista de strings que representam as tags definidas para o produto.
.product_type	String	Uma categorização com a qual um produto pode ser marcado com tag, geralmente usada para filtragem e pesquisa.
.vendor	String	Retorna o fabricante do produto.

Kernel

Kernel é um módulo do Ruby incluído em todas as classes. Como resultado, seus métodos estão disponíveis para todos os objetos. Esses métodos agem da mesma forma que as funções globais em outras linguagens.

Métodos de script que usam o objeto Kernel

Método	Tipo de retorno	Descrição
.exit	nenhum	Encerra a execução do script atual sem erros. Se for executado antes que algo seja atribuído a Output.cart, o script não terá efeito. É uma forma útil de encerrar scripts, por exemplo, se o cliente não estiver qualificado 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 item de linha

Os métodos a seguir só podem ser usados em scripts de item de linha:

Cart

Métodos de script que usam o objeto Cart em scripts de item de linha

Método	Tipo de retorno	Descrição
.subtotal_price_was	Money	Retorna o preço do subtotal do carrinho antes da aplicação de descontos.
.subtotal_price_changed?	Booleano	Retorna se o preço do subtotal mudou.

Item de linha

Métodos de script que usam o objeto LineItem em scripts de item de linha

Método	Tipo de retorno	Descrição
.change_line_price(Money new_price, { message: String })	Money	Altera o preço do item de linha para o valor especificado. É necessário incluir uma message. O new_price precisa ser inferior ao preço atual.
.original_line_price	Money	Retorna o preço original do item de linha antes da aplicação de scripts e descontos.
.line_price_was	Money	Retorna o preço do item de linha antes da aplicação de alterações pelo script atual.
.line_price_changed?	Booleano	Retorna se o preço do item de linha mudou.
.change_properties(hash new_properties, { message: String })	hash	Define novas propriedades para um item de linha. O hash de propriedades original é armazenado em properties_was, e o hash de propriedades que é passado para o método se torna as novas propriedades do item de linha.
.properties_was	hash	Retorna o hash de propriedades original do item de linha antes da aplicação de alterações.
.properties_changed?	Booleano	Retorna se as propriedades do item de linha foram alteradas.
.split({ take: Integer })	LineItem	Divide um item de linha em dois. take especifica a quantidade a ser removida do item de linha original para criar o novo.

Exemplo de .split

Este script de exemplo divide um item de linha chamado original_line_item em dois itens de linha. O novo item de linha tem a quantidade 1 (especificada por take: 1). Em seguida, o script aplica um preço com desconto ao novo item de linha com a mensagem “Terceiro chapéu 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 que usam o objeto Variant em scripts de item de linha

Método	Tipo de retorno	Descrição
.compare_at_price	Money	Retorna o preço de comparação da variante. Retorna nil se a variante não tiver um preço de comparação.

Métodos de frete

Os métodos a seguir podem ser usados em scripts de frete:

Entrada

Métodos de script que usam o objeto Input em scripts de frete

Método	Tipo de retorno	Descrição
.shipping_rates	ShippingRateList	Retorna uma lista com todas as taxas de frete.

ShippingRateList

Métodos de script que usam o objeto ShippingRateList em scripts de frete

Método	Tipo de retorno	Descrição
.delete_if	ShippingRateList	Exclui taxas de frete usando um bloco de código opcional. Consulte a documentação do método delete_if do Ruby.
.sort!	ShippingRateList	Classifica as taxas de frete usando o operador de comparação ou um bloco de código opcional. Consulte a documentação do método sort! do Ruby.
.sort_by!	ShippingRateList	Classifica as taxas de frete usando um bloco de código opcional. Consulte a documentação do método sort_by! do Ruby.

ShippingRate

Métodos de script que usam o objeto ShippingRate em scripts de frete

Método	Tipo de retorno	Descrição
.code	String	Retorna o código da taxa de frete.
.markup	Money	Retorna o markup de uma taxa de frete, se aplicável.
.name	String	Retorna o nome da taxa de frete. Ele pode ser modificado com o método change_name.
.price	Money	Retorna o preço da taxa de frete.
.source	String	Retorna a origem (a transportadora) associada à taxa de frete, se pertinente. Não é possível modificá-la.
.change_name(String new_name)	String	Altera o nome (máximo de 255 caracteres) da taxa de frete. Não é possível alterar, excluir nem ocultar a origem.
.apply_discount(Money discount, { message: String })	Money	Aplica um desconto do valor fixo especificado. O preço não pode ser reduzido para menos de 0. É obrigatório informar uma mensagem.
.phone_required?	Booleano	Retorna true se um número de telefone for obrigatório para obter a taxa de frete, ou false se não for.

Formas de pagamento

Os métodos a seguir podem ser usados em scripts de pagamento:

Entrada

Métodos de script que usam o objeto Input em scripts de pagamento

Método	Tipo de retorno	Descrição
.payment_gateways	PaymentGatewaysList	Retorna uma lista de todos os gateways de pagamento na loja.

PaymentGatewayList

Métodos de script que usam o objeto PaymentGatewayList em scripts de pagamento

Método	Tipo de retorno	Descrição
.delete_if	PaymentGatewayList	Exclui gateways de pagamento usando um bloco de código opcional. Consulte a documentação do método delete_if do Ruby.
.sort!	PaymentGatewayList	Classifica os gateways de pagamento usando o operador de comparação ou um bloco de código opcional. Consulte a documentação do método sort! do Ruby.
.sort_by!	PaymentGatewayList	Classifica os gateways de pagamento usando um bloco de código opcional. Consulte a documentação do método sort_by! do Ruby.

PaymentGateway

Método	Tipo de retorno	Descrição
.name	String	Retorna o nome do gateway de pagamento.
.enabled_card_brands	List<String>	Se o gateway de pagamento for compatível com cartões de crédito, retornará uma lista dos tipos de cartão de crédito que a loja aceita. Caso contrário, retornará uma lista vazia.
.change_name(String new_name)	String	Altera o nome do gateway de pagamento. Gateways de pagamento com logos não podem ser renomeados.

Exemplos

No exemplo de script de item de linha a seguir, quando um cliente pede um produto que não é um cartão-presente, o preço do produto é reduzido em US$ 9. Além disso, o valor total que o cliente gastou em todas as visitas à sua loja é exibido:

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

Saiba mais

Saiba mais sobre:

• Noções básicas do Ruby
• Criar scripts
• Testar e depurar seus scripts
• Atualizar seus modelos do Liquid para scripts
• Scripts da Shopify