Referência da API Shopify Scripts

Esta página foi impressa em May 09, 2024. Para a versão mais recente, acesse https://help.shopify.com/pt-BR/manual/checkout-settings/script-editor/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:

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:

Tudo pronto para começar a vender com a Shopify?

Experimente de graça