Prazo do Shopify Scripts: migre para Shopify Functions até 30 de junho de 2026

Hoje é 16 de abril de 2026. Ontem, 15 de abril, o Shopify bloqueou o Script Editor definitivamente. Você não pode mais criar nem publicar um novo Script. Esse prazo pesa sobretudo para a lógica relacionada a alterações após a compra: mudanças no endereço de entrega são a edição mais comum após a compra e representam 30,2% de todos os pedidos editados (Revize, 2026). Qualquer Script que ainda cuide dessas edições está agora congelado. A execução será encerrada em 75 dias, em 30 de junho de 2026.

Se você desenvolve para Shopify Plus — ou trabalha em uma agência responsável por uma loja Plus — e adiou essa migração para o “próximo sprint” nos últimos doze meses, há um problema. Não é algo que seria bom corrigir. É um problema que pode interromper a lógica do seu checkout à meia-noite de 1º de julho. A maioria das lojas Plus acumulou de 5 a 20 Scripts ao longo dos anos. Cada um executa discretamente uma regra de desconto, oculta uma opção de frete ou restringe uma forma de pagamento que ninguém se lembra de ter configurado.

Este guia é o manual técnico de migração que gostaríamos de ter tido em janeiro. Ele mostra o código de fato, além da estratégia. Ao terminar a leitura, você saberá como criar a estrutura de uma Function com a Shopify CLI, escrever a lógica em Rust ou JavaScript para descontos e personalizações de entrega e pagamento, testá-la com segurança em um grupo de clientes identificados por tag e colocá-la em produção sem interromper o checkout atual.

Vamos tirar os Scripts da sua loja e colocar as Functions para funcionar.

Resposta rápida: de Scripts para Functions em 60 segundos#

A migração em um parágrafo: Shopify Scripts (código Ruby no Script Editor, exclusivo do Plus) estão sendo substituídos por Shopify Functions (módulos WebAssembly escritos em Rust ou JavaScript, disponíveis em todos os planos). Você cria a estrutura de uma Function com shopify app generate extension, escreve uma consulta run.graphql para obter os dados necessários do carrinho e um arquivo run.rs ou run.js que retorna operações (descontos, opções de frete ocultas etc.). Depois, faz a implantação com shopify app deploy e ativa a Function pelo Shopify Admin ou por uma mutação GraphQL. As Functions executam como WASM compilado, com latência inferior a 5 ms, funcionam em todos os planos e são o único caminho de personalização que o Shopify oferecerá daqui para a frente.

O que muda, na prática, em 30 de junho#

Antes de mexer no código, tenha clareza sobre as datas. São duas, e ambas importam.

O resultado da migração é binário. Ou sua Function está implantada até 30 de junho e o checkout continua funcionando como esperado, ou não está — e todos os carrinhos afetados voltam discretamente aos preços padrão, às tarifas de frete padrão e a todas as formas de pagamento habilitadas. Não há meio-termo. O Script é executado ou não é. Depois de 30 de junho, não será.

Dica: Abra Settings → Checkout → Customizations Report no Shopify Admin. O relatório lista todos os Scripts ativos na loja, o que cada um faz e o tipo de Function recomendado para substituí-lo. Comece por ele.

Functions e Scripts: o que mudou de fato#

A mudança de arquitetura importa. Com Scripts, você ajustava Ruby em uma caixa de texto. Com Functions, você desenvolve um app, controla suas versões, testa localmente e faz a implantação por um pipeline de CI. A curva inicial é maior. Também deve ser a última migração da lógica de checkout que você fará no futuro próximo: Functions são a aposta de longo prazo do Shopify, não uma solução provisória como Scripts acabaram sendo.

Como associar cada Script ao tipo certo de Function#

Cada Script que você tem hoje corresponde a uma API de Function. Mantenha esta tabela por perto.

Se você tem dez Scripts, provavelmente criará de três a cinco Functions. Muitas vezes, vários Scripts podem ser reunidos em uma Function com uma lógica condicional mais clara.

Pré-requisito: prepare seu ambiente de desenvolvimento local#

Antes de criar a estrutura de qualquer Function, você precisa instalar três ferramentas localmente. Execute estas verificações no terminal.

1. Node.js 18+

node --version
# Must be >= 18.0.0

Se a versão for anterior, instale pelo nvm ou faça o download em nodejs.org.

2. Shopify CLI 3+

npm install -g @shopify/cli@latest
shopify version
# Should output 3.x or higher

3. Ferramentas de Rust (somente se você for escrever Functions em Rust)

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
rustup target add wasm32-wasip1
cargo --version

Functions em JavaScript não precisam de Rust. Escolha uma linguagem para a equipe e mantenha esse padrão. Misturar as duas aumenta o trabalho de manutenção.

4. Uma loja de desenvolvimento

Entre no painel de Parcerias e crie uma loja de desenvolvimento ou use uma que já exista. Você implantará as Functions nessa loja antes de levá-las à produção.

Como criar a estrutura da sua primeira Function#

A CLI gera a maior parte da estrutura inicial. Em qualquer diretório:

# Create a new Shopify app (skip if you already have one)
shopify app init my-checkout-functions
cd my-checkout-functions

# Generate a Function extension
shopify app generate extension

A CLI apresentará algumas opções. Para uma Function de desconto, você escolheria:

• Tipo: Function
• Modelo: discount (ou cart_checkout_validation, delivery_customization, payment_customization etc.)
• Linguagem: Rust ou JavaScript
• Nome: algo como volume-discount-fn

Isso cria extensions/volume-discount-fn/ com:

extensions/volume-discount-fn/
├── shopify.extension.toml      # Function config — targets, build, version
├── src/
│   ├── cart_lines_discounts_generate_run.graphql   # Input query
│   └── cart_lines_discounts_generate_run.rs        # Function logic
├── Cargo.toml                  # Rust dependencies (Rust only)
└── README.md

Os três arquivos que você editará com frequência são o .toml (configuração), o .graphql (entrada) e o .rs / .js (lógica). Só isso.

Tutorial 1: substituir um Line Item Script (desconto por volume)#

Suponha que seu Script antigo concedesse 10% de desconto sobre o subtotal do pedido sempre que o carrinho tivesse 5 ou mais unidades de uma coleção específica. Veja o equivalente em uma Function.

Etapa 1.1: a configuração (shopify.extension.toml)#

api_version = "2026-01"

[[extensions]]
name = "volume-discount-fn"
handle = "volume-discount-fn"
type = "function"

[[extensions.targeting]]
target = "cart.lines.discounts.generate.run"
input_query = "src/cart_lines_discounts_generate_run.graphql"
export = "cart_lines_discounts_generate_run"

[extensions.build]
command = "cargo build --target=wasm32-wasip1 --release"
path = "target/wasm32-wasip1/release/volume-discount-fn.wasm"
watch = ["src/**/*.rs"]

Etapa 1.2: a consulta de entrada (src/cart_lines_discounts_generate_run.graphql)#

query Input {
  cart {
    lines {
      id
      quantity
      cost {
        subtotalAmount {
          amount
        }
      }
      merchandise {
        ... on ProductVariant {
          product {
            inAnyCollection(ids: ["gid://shopify/Collection/123456789"])
          }
        }
      }
    }
  }
  discount {
    discountClasses
  }
}

Dica: As Functions só recebem os dados que você solicita na consulta. Mantenha o GraphQL enxuto: cada campo dispensado torna a execução mais rápida e econômica.

Etapa 1.3: a lógica (src/cart_lines_discounts_generate_run.rs)#

use super::schema;
use shopify_function::prelude::*;
use shopify_function::Result;

#[shopify_function]
fn cart_lines_discounts_generate_run(
    input: schema::cart_lines_discounts_generate_run::Input,
) -> Result<schema::CartLinesDiscountsGenerateRunResult> {
    // Bail if discount class doesn't match
    let has_order_discount = input
        .discount()
        .discount_classes()
        .contains(&schema::DiscountClass::Order);

    if !has_order_discount {
        return Ok(schema::CartLinesDiscountsGenerateRunResult { operations: vec![] });
    }

    // Sum quantities of items in the target collection
    let qualifying_qty: i64 = input
        .cart()
        .lines()
        .iter()
        .filter(|line| {
            if let schema::Merchandise::ProductVariant(v) = line.merchandise() {
                *v.product().in_any_collection()
            } else {
                false
            }
        })
        .map(|line| *line.quantity())
        .sum();

    if qualifying_qty < 5 {
        return Ok(schema::CartLinesDiscountsGenerateRunResult { operations: vec![] });
    }

    // Apply 10% off the order subtotal
    Ok(schema::CartLinesDiscountsGenerateRunResult {
        operations: vec![schema::CartOperation::OrderDiscountsAdd(
            schema::OrderDiscountsAddOperation {
                selection_strategy: schema::OrderDiscountSelectionStrategy::First,
                candidates: vec![schema::OrderDiscountCandidate {
                    targets: vec![schema::OrderDiscountCandidateTarget::OrderSubtotal(
                        schema::OrderSubtotalTarget {
                            excluded_cart_line_ids: vec![],
                        },
                    )],
                    message: Some("Volume discount: 10% off".to_string()),
                    value: schema::OrderDiscountCandidateValue::Percentage(
                        schema::Percentage { value: Decimal(10.0) }
                    ),
                    conditions: None,
                    associated_discount_code: None,
                }],
            },
        )],
    })
}

Etapa 1.4: teste, implante e ative#

# Local development with hot reload
shopify app dev

# When ready, deploy
shopify app deploy

# In the GraphiQL panel that opens (press `g` in the dev terminal),
# create the automatic discount that uses your Function:

mutation {
  discountAutomaticAppCreate(
    automaticAppDiscount: {
      title: "Volume Discount (5+ collection items)"
      functionHandle: "volume-discount-fn"
      discountClasses: [ORDER]
      startsAt: "2026-04-16T00:00:00Z"
    }
  ) {
    automaticAppDiscount { discountId }
    userErrors { field message }
  }
}

Pronto. A Function está ativa, tem controle de versões e substitui inteiramente o Script antigo.

Tutorial 2: substituir um Shipping Script (ocultar uma opção acima de um valor do carrinho)#

Um Script comum diz: “Oculte o frete expresso quando o subtotal do carrinho ultrapassar $500 para evitar o custo elevado de uma entrega no dia seguinte em pedidos grandes.” Veja a versão com uma Function de Delivery Customization.

Etapa 2.1: crie a estrutura#

shopify app generate extension --template delivery_customization --name hide-express-fn

Etapa 2.2: consulta de entrada (src/run.graphql)#

query Input {
  cart {
    cost {
      subtotalAmount {
        amount
      }
    }
    deliveryGroups {
      deliveryOptions {
        handle
        title
      }
    }
  }
}

Etapa 2.3: lógica (src/run.js — versão em JavaScript)#

// @ts-check
/**
 * @typedef {import("../generated/api").RunInput} RunInput
 * @typedef {import("../generated/api").FunctionRunResult} FunctionRunResult
 */

const NO_CHANGES = { operations: [] };
const THRESHOLD = 500.0;
const HIDE_TITLES = ["Express", "Overnight"];

/**
 * @param {RunInput} input
 * @returns {FunctionRunResult}
 */
export function run(input) {
  const subtotal = parseFloat(input.cart.cost.subtotalAmount.amount);
  if (subtotal < THRESHOLD) return NO_CHANGES;

  const operations = input.cart.deliveryGroups.flatMap((group) =>
    group.deliveryOptions
      .filter((opt) => HIDE_TITLES.some((t) => opt.title.includes(t)))
      .map((opt) => ({
        hide: { deliveryOptionHandle: opt.handle },
      }))
  );

  return { operations };
}

Etapa 2.4: ative pelo Admin (sem precisar de GraphQL)#

As Delivery Customizations têm uma interface integrada no Admin. Depois de shopify app deploy:

1. Acesse Settings → Shipping and delivery
2. Role até a seção Customizations, na parte inferior
3. Clique em Add customization → selecione sua Function
4. Salve

A regra para ocultar a opção está ativa em produção. Não é necessária nenhuma mutação.

Tutorial 3: substituir um Payment Script (ocultar pagamento na entrega para B2B)#

Script antigo: “Oculte o pagamento na entrega para qualquer cliente com a tag ‘B2B’.” Veja a versão com Payment Customization.

Etapa 3.1: crie a estrutura#

shopify app generate extension --template payment_customization --name hide-cod-b2b-fn

Etapa 3.2: consulta de entrada#

query Input {
  cart {
    buyerIdentity {
      customer {
        hasTags(tags: [{ tag: "B2B" }]) {
          tag
          hasTag
        }
      }
    }
  }
  paymentMethods {
    id
    name
  }
}

Etapa 3.3: lógica (src/run.js)#

const NO_CHANGES = { operations: [] };

export function run(input) {
  const tagCheck = input.cart?.buyerIdentity?.customer?.hasTags?.[0];
  const isB2B = tagCheck?.hasTag === true;
  if (!isB2B) return NO_CHANGES;

  const codMethod = input.paymentMethods.find((pm) =>
    pm.name.toLowerCase().includes("cash on delivery")
  );
  if (!codMethod) return NO_CHANGES;

  return {
    operations: [{ hide: { paymentMethodId: codMethod.id } }],
  };
}

Etapa 3.4: ative#

As Payment Customizations também têm uma interface no Admin, em Settings → Payments → Customizations. O processo é o mesmo da personalização de entrega: escolha sua Function e salve.

Já que você está aqui: uma observação sobre o pós-compra#

Uma breve informação, já que este é o blog da Revize. A Revize cuida do que as Functions não conseguem alterar: depois que o pedido é feito, os clientes podem querer adicionar um item, trocar um tamanho, corrigir o endereço de entrega ou aplicar um desconto que esqueceram. As Functions atuam no checkout. A Revize atua depois dele. As Functions determinam o que é permitido no carrinho; a Revize permite que seus clientes e sua equipe de atendimento editem o pedido depois, sem passar por um ciclo de reembolso e recriação do pedido. Isso importa para dois tipos de loja: aquelas com tantos pedidos que a edição manual se torna inviável (lojas Plus, claro, mas também lojas Advanced com alto volume de pedidos) e aquelas cuja marca depende da experiência do cliente — onde um e-mail dizendo “desculpe, não podemos mudar isso” pode custar uma nova compra.

Se seu plano de migração cobre Scripts → Functions, mas você ainda não resolveu a edição de pedidos após a compra, provavelmente encontrará o próximo obstáculo em cerca de três semanas. O guia de gestão de pedidos que acabamos de publicar apresenta o processo completo para o pós-checkout.

Voltemos à migração.

Estratégia de testes: o padrão de clientes identificados por tag#

As Functions não têm um “modo de rascunho” que você possa ativar no Admin. O padrão usado pelas equipes é limitar a nova Function a clientes com uma tag, executar o Script antigo e a nova Function em paralelo, verificar se produzem resultados idênticos para esses clientes e, então, liberar a Function para todos.

Etapa 1: adicione uma tag aos usuários de teste#

Em Customers, adicione a tag FN-TESTER a duas ou três contas internas.

Etapa 2: condicione a Function à presença da tag#

// At the top of your run function
let is_tester = input
    .cart()
    .buyer_identity()
    .and_then(|bi| bi.customer())
    .map(|c| c.has_any_tag())
    .unwrap_or(&false);

if !*is_tester {
    return Ok(default_result);  // Fall through to existing Script
}

// New Function logic only runs for tagged users

Etapa 3: adicione hasAnyTag à consulta de entrada#

cart {
  buyerIdentity {
    customer {
      hasAnyTag(tags: ["FN-TESTER"])
    }
  }
}

Etapa 4: verifique no checkout#

Entre como um usuário com a tag, passe pelo checkout e confirme que a Function é executada. Depois, entre como um usuário sem a tag e confirme que o Script antigo continua funcionando. Quando os resultados forem equivalentes por alguns dias, remova a verificação da tag e deixe a Function ser executada para todos.

Etapa 5: cancele a publicação do Script antigo#

Acesse Apps → Script Editor → [Your Script] → Unpublish. Depois que o Script deixar de estar publicado, a Function será a única fonte da lógica.

Um fluxo de implantação que acompanha o crescimento da loja#

Não dependa indefinidamente do laptop de um desenvolvedor para fazer implantações. Depois de migrar um ou dois Scripts, configure um pipeline de CI.

O fluxo mínimo necessário#

# .github/workflows/deploy-functions.yml
name: Deploy Shopify Functions
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20' }
      - uses: dtolnay/rust-toolchain@stable
        with: { targets: wasm32-wasip1 }
      - run: npm install -g @shopify/cli@latest
      - run: shopify app deploy --force
        env:
          SHOPIFY_CLI_PARTNERS_TOKEN: ${{ secrets.SHOPIFY_CLI_PARTNERS_TOKEN }}

Gere o token de parceiro no painel de Parcerias, em Settings → Tokens. A partir daí, cada merge na main implanta suas Functions. Chega de conversas no Slack perguntando “o Mike fez a implantação?”.

Versionamento e reversão#

shopify app deploy cria um registro versionado. Para voltar a uma versão anterior:

shopify app versions list
shopify app release --version <previous-version-id>

Com Scripts, reverter significava lembrar qual era o código antigo e colá-lo de volta. A diferença é grande.

Onde a maioria das equipes erra#

Depois de ajudar lojistas Plus nessa migração ao longo do último ano, vimos os mesmos cinco erros se repetirem.

1. Tratar Functions como uma conversão individual de cada Script. Não é assim que funciona. Uma única Function pode substituir três Scripts com uma lógica condicional mais clara. Avalie seus Scripts em conjunto antes de reescrevê-los.

2. Esquecer os escopos de leitura. Muitas Functions precisam de read_customers, read_orders ou write_discounts. Adicione esses escopos em shopify.app.toml, em scopes, e autorize o app novamente. Caso contrário, a consulta de entrada retornará null.

3. Executar Functions para clientes sem a tag antes de comparar os resultados. Mesmo que o código pareça correto, casos específicos — carrinho vazio, cartões-presente, crédito na loja, rascunhos B2B — podem revelar problemas. Uma liberação controlada por tag custa dois dias e pode evitar uma falha crítica.

4. Ignorar o Customizations Report. Ele é o inventário mais útil do que está realmente em execução. Baseie a migração no relatório, não na memória.

5. Fixar IDs de coleções e tags de clientes no código. Se os valores precisarem ser ajustados pelo lojista, use a configuração da Function por metacampos. A CLI pode criar a estrutura dessa configuração. Consulte a documentação do Shopify sobre configuração de Functions.

Checklist de migração para os próximos 75 dias#

Um plano realista, semana a semana, para chegar a 30 de junho com tranquilidade.

Se você começar esta semana, terá uma margem. Se começar em junho, não terá.

O que fazer esta semana#

Não feche a aba depois de ler este artigo. Faça estas quatro coisas nos próximos sete dias.

1. Obtenha o Customizations Report. Acesse Settings → Checkout → Customizations Report e exporte o relatório. Essa será sua lista de tarefas para a migração.

2. Prepare seu ambiente de desenvolvimento. Instale Node 18+, Shopify CLI e Rust (se aplicável). Confirme que shopify version funciona. Tempo total: 30 minutos.

3. Crie e implante uma Function pequena em uma loja de desenvolvimento. Escolha o Script mais simples que você tem — geralmente uma regra que oculta uma forma de pagamento. Migre-o do início ao fim. Mesmo que ele nunca vá para produção, você terá validado as ferramentas.

4. Reserve horários na agenda para as próximas oito semanas. Migrações não acontecem nos intervalos entre sprints. Separe um período recorrente — por exemplo, todas as terças e quintas à tarde — e trate esse trabalho como uma entrega.

Entre as equipes que vimos migrar, o padrão é consistente: duas semanas de adiamento, três semanas de trabalho efetivo e uma semana de ajustes finais. São seis semanas. Você tem dez. Use a margem para revisão de código e testes de qualidade, não para adiar o início.

E, depois de resolver a lógica do checkout, a próxima questão para a maioria das equipes é o pós-compra: mudanças de endereço, trocas e inclusão de descontos após a realização do pedido. Se isso está nos seus planos (e deveria estar, seja você responsável por uma operação Plus de alto volume ou por uma loja Advanced focada na experiência do cliente), a Revize está na Shopify App Store e funciona junto com todas as Functions que você criará aqui.

Recursos#

• Visão geral do Shopify Functions — documentação para desenvolvedores do Shopify
• Migração de Shopify Scripts para Functions
• Tutorial para criar uma Function de desconto
• Referência da Delivery Customization Function API
• Referência da Payment Customization Function API
• Documentação da Shopify CLI

Atualizado em agosto de 2026. A Revize é um app para Shopify que permite aos clientes editar seus próprios pedidos após a compra. Antes do processamento de pedidos (fulfillment), eles podem alterar o endereço de entrega, trocar uma variante ou um produto, cancelar o pedido e receber um reembolso ou crédito na loja, sem abrir um chamado de atendimento. Saiba mais sobre como permitir que os clientes editem seus próprios pedidos no Shopify ou encontre a Revize na Shopify App Store.