Referência da API Shopify Scripts

Os scripts são compilados por meio de uma API Ruby que proporciona considerável controle e flexibilidade.

Há diferentes tipos de script. A atribuição do tipo de script acontece quando o script é criado no app Script Editor com base no modelo que você escolheu para começar:

Scripts de itens de linha

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

Os scripts de item de linha para desconto se aplicam apenas ao primeiro pagamento de uma assinatura. Os pagamentos seguintes não são afetados.

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

Scripts de frete

Esses scripts interagem com o frete e podem afetar as formas e os descontos concedidos no frete. Eles são executados ao acessar a página de opções de frete do checkout.

Os scripts de frete que concedem descontos à taxa de frete de uma assinatura se aplicam apenas ao primeiro pagamento. Os pagamentos seguintes não são afetados.

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

Scripts de pagamento

Esses scripts interagem com pagamentos e podem renomear, ocultar e reordenar gateways de pagamento. Observe que os scripts de pagamento não interagem com os gateways de pagamento mostrados antes da tela de checkout, como o Apple Pay. Esses scripts são executados quando o checkout acessa a página de pagamentos.

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

Nesta página

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 devolução	Descrição
.cart	Carrinho	Retorna um objeto "cart" mutável.
.locale	string	Retorna a localidade do cliente. Por exemplo, `en` , `fr` ou `pt-BR`.

Carrinho

O objeto "carrinho" só está disponível na loja virtual. Alguns carrinhos abandonados têm acesso ao objeto "carrinho". No entanto, se um carrinho foi fechado e, em seguida, o cliente decidir acessá-lo, ele será enviado para o carrinho pré-preenchido e o objeto "carrinho" não existirá mais. Isso ocorre porque a vitrine foi ignorada pelo e-mail de carrinho abandonado.

Métodos de script usando o objeto Cart
Método	Tipo de devolução	Descrição
.customer	Cliente	Retorna o proprietário do carrinho (caso aplicável).
.shipping_address	Endereço de entrega	Retorna o endereço de entrega do proprietário do carrinho (caso aplicável).
.discount_code	varia	Retorna: `nil` se o carrinho não incluir nenhum código de desconto `CartDiscount::FixedAmount` se o carrinho incluir um valor de desconto fixo `CartDiscount::Percentage` se o carrinho incluir um desconto percentual `CartDiscount::Shipping` se o carrinho incluir um desconto de frete Retorna um único código de desconto (consulte Limitações) O `discount_code` está presente se houver um desconto aplicado ao carrinho. Isso não significa necessariamente que o preço do carrinho mudará. Por exemplo, se há um desconto aplicável a carrinhos acima de US$ 50 e um script reduz o preço do carrinho para menos de US$ 50, o `discount_code` ainda está presente, mas o preço do carrinho não é alterado. Veja um exemplo de `discount_code`.
.line_items	Listar<LineItem>	Retorna uma lista contendo os itens de linha do carrinho.
.presentment_currency	Listar<String>	Retorna a moeda (de apresentação) local do cliente (em formato ISO 4217). Por exemplo, USD.
.subtotal_price	Dinheiro	Retorna o preço do subtotal do carrinho depois da aplicação de descontos aos itens de linha, mas antes da aplicação de códigos de desconto.
.total_weight	gramas	Retorna o peso total de todos os itens de linha do carrinho.

CartDiscount::FixedAmount

Métodos de script usando o objeto CartDiscount::FixedAmount
Método	Tipo de devolução	Descrição
.code	String	Retorna o código de desconto usado para aplicar o desconto.
.amount	Dinheiro	Retorna a quantia em dinheiro do desconto.
.reject({ message: String })	nil	Recusa o código de desconto aplicado ao carrinho. É preciso haver uma `mensagem`.
.rejected?	Booleano	Retorna se o código de desconto foi recusado.

CartDiscount::Percentage

Métodos de script usando o objeto CartDiscount::Percentage
Método	Tipo de devolução	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. É preciso haver uma `mensagem`.
.rejected?	Booleano	Retorna se o código de desconto foi recusado.

CartDiscount::Shipping

Métodos de script usando o objeto CartDiscount::Shipping
Método	Tipo de devolução	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. É preciso haver uma `mensagem`.
.rejected?	Booleano	Retorna se o código de desconto foi recusado.

Cliente

Métodos de script usando o objeto Customer
Método	Tipo de devolução	Descrição
.id	Inteiro	Retorna o número de ID do cliente.
.email	String	Retorna o endereço de e-mail do cliente.
.tags	Listar <Tag>	Retorna uma lista de strings representando qualquer conjunto de tags de um cliente.
.orders_count	Inteiro	Retorna o número total de pedidos feitos pelo cliente.
.total_spent	Dinheiro	Retorna o valor total gasto pelo cliente em todos os pedidos.
.accepts_marketing?	Booleano	Retorna se o cliente aceita marketing.

LineItem

<tdgrams

Métodos de script usando o objeto LineItem
Método	Tipo de devolução	Descrição
.grams	Retorna o peso total do item de linha.
.line_price	Dinheiro	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 código de desconto aplicado manualmente. O uso de códigos de desconto não afeta o valor retornado.
.properties	hash	Retorna as propriedades que foram especificadas para os itens de linha.
.variant	Variante	Retorna a variante de produto específica representada pelo item de linha.
.quantity	Inteiro	Retorna a quantidade do 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 assinatura.

Lista

Métodos de script usando o objeto List
Método	Tipo de devolução	Descrição
.new	Lista	Cria um novo objeto para representar uma lista.
.[]	Element ou nil	Retorna o elemento no índice especificado.
.&	Lista	Retorna uma nova lista contendo elementos comuns às duas listas, sem duplicatas.
.delete_if	Lista	Exclua elementos usando um bloco de código opcional. Confira a documentação do método `delete_if` do Ruby.
.empty?	Booleano	Retorna `true (verdadeiro)` se a lista não incluir elementos.
.first	Element ou nil	Retorna o primeiro elemento ou `nil (nulo)` se a lista estiver vazia.
.index(*args, &block)	int ou nil	Retorna o índice do primeiro elemento da lista. Se for oferecido um bloco 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 for oferecido um bloco em vez de um argumento, retorna o índice do primeiro elemento para o qual o bloco é verdadeiro.
.last	Element ou nil	Retorna o último elemento ou `nil` se a lista estiver vazia.
.length	int	Retorna o número de elementos da lista.
.size	int	Alias para comprimento.
.each(*args, &block)	Lista	Chama um bloco uma vez para cada elemento na lista, passando o elemento como parâmetro ao bloco.

Endereço de entrega

Métodos de script usando o objeto ShippingAddress
Método	Tipo de devolução	Descrição
.name	string	Retorna o nome da pessoa associada ao endereço de entrega.
.address1	string	Retorna a parte do endereço de entrega referente ao endereço postal.
.address2	string	Retorna o campo adicional opcional do endereço de entrega referente ao endereço postal.
.phone	string	Retorna o número de celular 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 usando o objeto Money
Método	Tipo de devolução	Descrição
.derived_from_presentment(customer_cents:X)	Dinheiro	Converte um valor (em centavos) na moeda (de apresentação) local do cliente para a moeda de sua loja. Este método aceita o parâmetro `customer_cents`, que exibe os números em centavos. Por exemplo, `Money.derived_from_presentment(customer_cents: 500)`.
.new	Dinheiro	Cria um novo objeto para representar um preço.
.zero	Dinheiro	Cria um novo objeto com o preço zero.
+	Dinheiro	Adiciona dois objetos `Money`.
-	Dinheiro	Subtrai um objeto `Money` de outro objeto.
*	Dinheiro	Multiplica um objeto `Money` por um número.

Exemplos de Money

Money.new(cents: 1000)

Cria um objeto Money representando mil centavos de dólar ou US$ 10.

Money.new(cents: 100) * 50

Cria um objeto Money representando US$ 1, multiplicando esse valor por 50. Retorna um objeto Money representando US$ 50.

Variante

Métodos de script usando o objeto Variant
Método	Tipo de devolução	Descrição
.id	Inteiro	Retorna o número de ID da variante.
.price	Dinheiro	Retorna o preço unitário da variante.
.product	Produto	Retorna o produto associado da variante.
.skus	Listar<String>	Retorna as SKUs (Unidades de manutenção de estoque) da variante, que geralmente são usadas para acompanhar o estoque.
.title	String	Retorna o título da variante.

Produto

Métodos de script usando o objeto Product
Método	Tipo de devolução	Descrição
.id	Inteiro	Retorna o número de ID do produto.
.gift_card?	Booleano	Retorna se o produto é um cartão-presente.
.tags	Listar <Tag>	Retorna uma lista de strings representando as tags definidas para esse produto.
.product_type	String	Uma categorização com a qual um produto pode ser marcado, normalmente usada para filtragem e pesquisa.
.vendor	String	Retorna o fornecedor do produto.

Kernel

Kernel é um módulo Ruby que está incluído em todas as classes. Como resultado, seus métodos estão disponíveis para cada um dos objetos. Esses métodos agem da mesma maneira que as funções globais em outros idiomas.

Métodos de script usando o objeto Kernel
Método	Tipo de devolução	Descrição
.exit	nenhum	Encerra a execução do script atual sem erros. Se isso for executado antes que qualquer coisa seja atribuída a `Output.cart`, o script não terá efeito. Essa é uma maneira útil de sair de 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 podem ser usados apenas em scripts de item de linha:

Carrinho

Métodos de script usando o objeto Cart nos scripts de itens de linha
Método	Tipo de devolução	Descrição
.subtotal_price_was	Dinheiro	Retorna o preço subtotal do carrinho antes da aplicação de qualquer desconto.
.subtotal_price_changed?	Booleano	Retorna se o preço subtotal foi alterado.

LineItem

Métodos de script usando o objeto LineItem em scripts de itens de linha
Método	Tipo de devolução	Descrição
.change_line_price(Money new_price, { message: String })	Dinheiro	Altere o preço do item de linha para o valor especificado. É preciso haver uma `mensagem`. `new_price` precisa ser menor que o preço atual.
.original_line_price	Dinheiro	Retorna o preço original do item de linha antes da aplicação de scripts e descontos.
.line_price_was	Dinheiro	Retorna o preço do item de linha antes de o script atual aplicar as alterações.
.line_price_changed?	Booleano	Retorna se o preço do item de linha foi alterado.
.change_properties(hash new_properties, { message: String })	hash	Define novas propriedades para os itens de linha. O hash de propriedades original é armazenado em `properties_was`, e o hash de propriedades passado ao método passa a ser 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 qualquer alteração.
.properties_changed?	Booleano	Retorna se as propriedades do item de linha foram alteradas.
.split({ take: Integer })	LineItem	Divide um item de linha em dois itens de linha. `take` especifica qual quantidade remover do item de linha original para criar o novo item de linha.

Exemplo de .split

Este exemplo de script divide um item de linha chamado original_line_item em dois itens de linha. O novo item de ilha tem uma quantidade de 1 (especificado 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 usando o objeto Variant em scripts de itens de linha
Método	Tipo de devolução	Descrição
.compare_at_price	Dinheiro	Retorna a Comparação de preços da variante. Retorna `nil` se não houver uma Comparação de preços para a variante.

Formas de frete

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

Entrada

Métodos de script usando o objeto Input nos scripts de frete
Método	Tipo de devolução	Descrição
.shipping_rates	ShippingRateList	Retorna uma lista de todas as taxas de frete.

ShippingRateList

Métodos de script usando o objeto ShippingRateList em scripts de frete
Método	Tipo de devolução	Descrição
.delete_if	ShippingRateList	Exclua taxas de frete usando um bloco de código opcional. Confira a documentação do método `delete_if` do Ruby.
.sort!	ShippingRateList	Organize as taxas de frete usando o operador de comparação ou um bloco de código opcional. Confira a documentação do método `sort!` do Ruby.
.sort_by!	ShippingRateList	Organize as taxas de frete usando um bloco de código opcional. Confira a documentação do método `sort_by!` do Ruby.

ShippingRate

Métodos de script usando o objeto ShippingRate em scripts de frete
Método	Tipo de devolução	Descrição
.code	String	Retorna o código da taxa de frete.
.markup	Dinheiro	Retorna a marcação para uma taxa de frete, se aplicável.
.name	String	Retorna o nome da taxa de frete. Ele pode ser modificado usando o método `change_name`.
.price	Dinheiro	Retorna o preço da taxa de frete.
.source	String	Retorna a origem (a transportadora) associada à taxa de frete, se relevante. Não pode ser modificado.
.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 })	Dinheiro	Aplica um desconto do valor fixo especificado. O preço não pode ser reduzido para menos de 0. Uma mensagem é necessária.
.phone_required?	Booleano	Retorna `true (verdadeiro)` se for necessário um número de celular para obter a taxa de frete ou `false (falso)` se não for necessário o número de celular.

Formas de pagamento

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

Entrada

Métodos de script usando o objeto Input nos scripts de pagamento
Método	Tipo de devolução	Descrição
.payment_gateways	PaymentGatewaysList	Retorna uma lista de todos os gateways de pagamento da loja.

PaymentGatewayList

Métodos de script usando o objeto PaymentGatewayList em scripts de pagamento
Método	Tipo de devolução	Descrição
.delete_if	PaymentGatewayList	Exclua gateways de pagamento usando um bloco de código opcional. Confira a documentação do método `delete_if` do Ruby.
.sort!	PaymentGatewayList	Organize os gateways de pagamento usando o operador de comparação ou um bloco de código opcional. Confira a documentação do método Ruby's `sort!`.
.sort_by!	PaymentGatewayList	Organize os gateways de pagamento usando um bloco de código opcional. Confira a documentação do método `sort_by!` do Ruby.

PaymentGateway

Método	Tipo de devolução	Descrição
.name	String	Retorna o nome do gateway de pagamento.
.enabled_card_brands	Listar<String>	Se o gateway de pagamento for compatível com cartões de crédito, retorna uma lista dos tipos de cartões de crédito aceitos pela loja. Se o gateway não for compatível com cartões de crédito, retorna uma lista vazia.
.change_name(String new_name)	String	Altera o nome do gateway de pagamento. Vale lembrar que não é possível renomear esses serviços com logos.

Exemplos

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

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: