Shopify Scripts após 30 de junho de 2026: migração para Functions

Em 14 de outubro de 2026, os dois marcos de Shopify Scripts já passaram: editar e publicar deixou de ser possível em 15 de abril, e a execução parou em 30 de junho. Revise o Customizations Report da Shopify e identifique comportamentos do checkout que dependiam de Scripts.

Este guia explica como avaliar personalizações afetadas e usar Shopify Functions para lógica compatível de descontos, entrega e pagamento. Scripts tratavam o comportamento do checkout; não implementavam edições pós-compra, como alterar o endereço de envio após o pedido.

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

Situação atual: Shopify Scripts deixaram de executar em 30 de junho de 2026. Shopify Functions oferecem APIs compatíveis para personalizações de checkout, como descontos, entrega e pagamento. Apps públicos que usam Functions estão disponíveis em todos os planos; apps personalizados com Functions exigem Shopify Plus. Comece pelo guia de migração da Shopify e pelo modelo atual de extensão gerado pela CLI, depois valide o comportamento em uma loja de desenvolvimento.

O que mudou em 2026#

As datas anunciadas pela Shopify já passaram. O Script Editor ficou somente leitura em 15 de abril, e Scripts deixaram de executar em 30 de junho de 2026.

Se uma loja dependia de um Script, seu comportamento parou após o prazo, a menos que tivesse sido substituído ou reconfigurado. Confira o checkout real da loja; não presuma que todas as configurações afetadas tenham o mesmo comportamento de fallback.

Dica: Revise o Customizations Report no admin da Shopify para inventariar personalizações afetadas pelo encerramento dos Scripts. Use a documentação atual de migração para confirmar a substituição de cada uma.

Functions e Scripts: o que mudou de fato#

A mudança de arquitetura importa: Scripts eram personalizações Ruby no Script Editor; Functions são extensões de app desenvolvidas com as ferramentas compatíveis da Shopify. Seus targets e requisitos de plano diferem, então use a documentação de migração para mapear cada Script a uma substituição compatível.

Como associar cada Script ao tipo certo de Function#

Um Script pode corresponder a uma Function, um app público, outra configuração compatível ou nenhuma substituição. Use o guia de migração da Shopify para conferir a opção correta para cada personalização.

Vários Scripts podem corresponder a uma Function ou exigir substituições separadas. Confirme o mapeamento e o comportamento de cada caso antes de combinar a lógica.

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#

Use uma versão de Node.js compatível com a versão atual da Shopify CLI; confira os requisitos de instalação antes de configurar o projeto.

node --version
# Check the version required by your installed Shopify CLI

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

2. Shopify CLI atual#

Instale a versão atual da Shopify CLI e verifique com shopify version. Para o crate atual de Rust Function (2.0.0 e posteriores), a Shopify documenta CLI 3.85.0 ou superior.

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-unknown-unknown
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 --name 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-10"
 
[[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-unknown-unknown --release"
path = "target/wasm32-unknown-unknown/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 CreateAutomaticDiscount($startsAt: DateTime!) {
  discountAutomaticAppCreate(
    automaticAppDiscount: {
      title: "Volume Discount (5+ collection items)"
      functionHandle: "volume-discount-fn"
      discountClasses: [ORDER]
      startsAt: $startsAt
    }   
  ) {
    automaticAppDiscount { discountId }
    userErrors { field message }
  }  
}  

No painel Query Variables do GraphiQL, defina startsAt como um timestamp ISO 8601 futuro. Revise campos obrigatórios adicionais para sua versão da API antes de executar a mutação.

Isso cria o desconto automático que chama a Function implantada; ela substitui a lógica do Script para esse caso de uso.

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.

Os tutoriais 2 e 3 usam os modelos JavaScript atuais. Mantenha os targets gerados e as exportações de src/index.js, defina api_version = "2026-10" no arquivo shopify.extension.toml de cada extensão e execute shopify app function typegen no diretório de cada extensão após substituir a consulta de entrada.

Etapa 2.1: crie a estrutura#

shopify app generate extension --template delivery_customization --flavor vanilla-js --name hide-express-fn

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

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

Etapa 2.3: lógica (src/cart_delivery_options_transform_run.js)#

// @ts-check
/**
 * @typedef {import("../generated/api").CartDeliveryOptionsTransformRunInput} CartDeliveryOptionsTransformRunInput
 * @typedef {import("../generated/api").CartDeliveryOptionsTransformRunResult} CartDeliveryOptionsTransformRunResult
 */
           
/** @type {CartDeliveryOptionsTransformRunResult} */
const NO_CHANGES = { operations: [] };
const THRESHOLD = 500.0;
const HIDE_TITLES = ["Express", "Overnight"];
            
/** 
 * @param {CartDeliveryOptionsTransformRunInput} input
 * @returns {CartDeliveryOptionsTransformRunResult}
 */ 
export function cartDeliveryOptionsTransformRun(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) => ({
        deliveryOptionHide: { deliveryOptionHandle: opt.handle },
      }))
  );
              
  return { operations };
}    

Etapa 2.4: crie e ative a personalização de entrega#

Após executar shopify app deploy e instalar o app na loja de destino, execute deliveryCustomizationCreate pelo cliente Admin GraphQL autenticado desse app, com o escopo write_delivery_customizations. Defina a variável functionHandle como o handle da extensão em shopify.extension.toml (por exemplo, hide-express-fn).

mutation CreateDeliveryCustomization($functionHandle: String!) {
  deliveryCustomizationCreate(deliveryCustomization: {
    functionHandle: $functionHandle
    title: "Hide express shipping above cart threshold"
    enabled: true
  }) {
    deliveryCustomization { id enabled }
    userErrors { field message }
  }
}

Confirme que a resposta retorna uma personalização ativada e nenhum userErrors. Em seguida, confira Configurações → Frete e entrega → Personalizações de entrega e teste o comportamento do checkout. A implantação disponibiliza a Function; essa mutação cria e ativa a personalização da loja.

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 --flavor vanilla-js --name hide-cod-b2b-fn

Etapa 3.2: consulta de entrada (src/cart_payment_methods_transform_run.graphql)#

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

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

// @ts-check
/**
 * @typedef {import("../generated/api").CartPaymentMethodsTransformRunInput} CartPaymentMethodsTransformRunInput
 * @typedef {import("../generated/api").CartPaymentMethodsTransformRunResult} CartPaymentMethodsTransformRunResult
 */
/** @type {CartPaymentMethodsTransformRunResult} */
const NO_CHANGES = { operations: [] }; 
               
/**
 * @param {CartPaymentMethodsTransformRunInput} input
 * @returns {CartPaymentMethodsTransformRunResult}
 */
export function cartPaymentMethodsTransformRun(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: [{ paymentMethodHide: { paymentMethodId: codMethod.id } }],
  };
}      

Etapa 3.4: crie e ative a personalização de pagamento#

Após implantar e instalar o app na loja de destino, execute paymentCustomizationCreate pelo cliente Admin GraphQL autenticado desse app, com o escopo write_payment_customizations. Defina functionHandle como o handle da extensão de pagamento em shopify.extension.toml (por exemplo, hide-cod-b2b-fn).

mutation CreatePaymentCustomization($functionHandle: String!) {
  paymentCustomizationCreate(paymentCustomization: {
    functionHandle: $functionHandle
    title: "Hide Cash on Delivery for B2B-tagged customers"
    enabled: true
  }) {
    paymentCustomization { id enabled }
    userErrors { field message }
  }
}

Confira se a resposta contém uma personalização de pagamento ativada, sem userErrors. Verifique-a em Configurações → Pagamentos → Personalizações de pagamento e teste o checkout com clientes com e sem a tag B2B.

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

Para alterações após o checkout, Revize oferece autoatendimento elegível antes do processamento pela página de status do pedido ou por um link no e-mail de confirmação durante a janela definida pelo lojista. Trocar por outro produto e adicionar produtos exigem Pro; a edição pela equipe está em desenvolvimento. Os clientes revisam qualquer saldo adicional e pagam pelo checkout Shopify. O guia Gestão de pedidos Shopify 2026: guia para operações Plus cobre o fluxo nativo após o checkout.

Voltemos à migração.

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

Use uma loja de desenvolvimento e dados de entrada representativos para testar a substituição diante dos requisitos documentados ou resultados salvos de testes de Scripts. Scripts não executam mais, então um teste em paralelo ao vivo de Script/Function não está mais disponível. Uma restrição por tag de cliente pode limitar uma Function de teste a contas internas enquanto você verifica o comportamento; mantenha a implementação em produção separada desses testes.

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#

// Rust example: return this target's empty result for non-testers
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);  // No operations from this Function
}       
                   
// 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 e verifique carrinhos que atendem e que não atendem às condições, combinações de descontos e opções de entrega/pagamento. Repita com um usuário sem a tag para confirmar que essa Function não retorna operações. Compare os resultados com o comportamento esperado registrado da lógica antiga; inclua checkout de visitantes nos testes antes de remover a restrição.

Etapa 5: revise a ativação em produção#

Ative a substituição testada na configuração adequada de desconto, entrega ou pagamento. Registre a versão do app implantada e o plano de reversão e remova instruções obsoletas de Scripts da documentação da equipe.

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: '22' }
      - uses: dtolnay/rust-toolchain@stable
        with: { targets: wasm32-unknown-unknown }
      - run: npm install -g @shopify/cli@latest
      - run: shopify app deploy --force
        env:
          SHOPIFY_APP_AUTOMATION_TOKEN: ${{ secrets.SHOPIFY_APP_AUTOMATION_TOKEN }}

Crie um App Automation Token no Dev Dashboard Shopify e armazene-o como o segredo do repositório mostrado acima. A CLI atual exige Node.js 22.12 ou posterior. Associe o projeto à configuração do app antes de usar CI; adicione etapas de teste e revisão de lançamento antes da implantação. Este exemplo implanta em um push para main, então adapte o acionador à política de lançamentos da equipe.

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#

Estas são armadilhas comuns de migração para verificar antes de lançar uma Function.

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. Confundir escopos do app com dados de entrada da Function. Uma Function lê os campos expostos pela consulta de entrada e metacampos configurados; não ganha acesso à Admin API ao adicionar read_customers ou read_orders. Adicione escopos apenas para operações separadas da Admin API e confira as regras de entrada e configuração da Function API para a extensão que está criando.

3. Pular testes de paridade. Compare a Function com o Script antigo usando carrinhos representativos e casos extremos relevantes antes do lançamento. Use uma implantação gradual apenas quando a extensão e a configuração permitirem.

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.

Lista de verificação da migração#

Use esta lista para revisar o estado atual de uma migração de Scripts.

Como o prazo de execução passou, priorize a auditoria do checkout em produção e qualquer trabalho restante de substituição.

Próximas etapas#

1. Revise o Customizations Report e o guia atual de migração da Shopify.
2. Teste os casos relevantes de checkout em uma loja de desenvolvimento.
3. Confirme quais Functions ou apps públicos permitem a lógica necessária no seu plano.
4. Verifique cada substituição em produção e documente o responsável e a configuração.

Mantenha os testes de regras de checkout separados dos testes de edição pós-compra. Para cada sistema, registre o app responsável, os recursos ativados e o comportamento de processamento/pagamento para que alterações futuras tenham um responsável claro.

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

Leitura relacionada: Estatísticas de edição de pedidos Shopify (2026) · Como permitir que os clientes editem os próprios pedidos Shopify (2026)