Shopify Scripts dopo il 30 giugno 2026: migrare a Functions

A partire dal 14 ottobre 2026, entrambi i traguardi di Shopify Scripts sono stati superati: la modifica e la pubblicazione sono state interrotte il 15 aprile e l’esecuzione degli script è stata interrotta il 30 giugno. Esamina il report sulle personalizzazioni di Shopify e identifica eventuali comportamenti di pagamento che dipendevano dagli script.

Questa guida spiega come valutare le personalizzazioni interessate e utilizzare le Shopify Functions per la logica di sconto, consegna e pagamento supportata. Gli script gestivano il comportamento di pagamento; non hanno implementato modifiche all’ordine post-acquisto come la modifica di un indirizzo di spedizione dopo aver effettuato un ordine.

Risposta rapida: da Scripts a Functions in 60 secondi#

Stato attuale: L’esecuzione degli Shopify Scripts è stata interrotta il 30 giugno 2026. Le Shopify Functions forniscono API supportate per personalizzazioni del checkout come sconti, consegna e pagamento. Le app pubbliche che utilizzano le funzioni sono disponibili in tutti i piani; le app personalizzate che contengono funzioni richiedono Shopify Plus. Inizia con la guida alla migrazione di Shopify e l’attuale modello di estensione generato dalla CLI, quindi convalida il comportamento in un negozio di sviluppo.

Cosa è cambiato nel 2026#

Le date annunciate da Shopify sono passate. L’editor degli script è diventato di sola lettura il 15 aprile e l’esecuzione degli script è stata interrotta il 30 giugno 2026.

Se un negozio dipendeva da uno script, il suo comportamento smetteva di funzionare dopo l’interruzione a meno che non fosse stato sostituito o riconfigurato in altro modo. Controllare l’effettivo comportamento di pagamento nel negozio; non dare per scontato che tutte le impostazioni interessate ricadano allo stesso modo.

Suggerimento: esamina il Report sulle personalizzazioni in Shopify Admin per verificare le personalizzazioni dell’inventario interessate dalla disattivazione degli script. Utilizza l’attuale documentazione di migrazione di Shopify per confermare la sostituzione per ciascuno di essi.

Functions e Scripts: cosa è cambiato davvero#

Il cambiamento architetturale è importante: gli script erano personalizzazioni di Ruby nello Script Editor; Le funzioni sono estensioni dell’app sviluppate con gli strumenti supportati da Shopify. Gli obiettivi dell’estensione e i requisiti del piano differiscono, quindi utilizza la documentazione sulla migrazione per associare ogni script a una sostituzione supportata.

Associare ogni Script al tipo di Function giusto#

Uno script può essere associato a una funzione, a un’app pubblica, a un’impostazione supportata diversa o a nessuna sostituzione. Utilizza la guida alla migrazione di Shopify per verificare l’opzione corretta per ciascuna personalizzazione.

Diversi script possono essere associati a una funzione o richiedere sostituzioni separate. Confermare la mappatura e il comportamento per ciascun caso prima di combinare la logica.

Prerequisito: prepara l’ambiente di sviluppo locale#

Prima di creare una Function, devi installare tre strumenti in locale. Esegui questi controlli nel terminale.

1. Node.js#

Utilizza una versione Node.js supportata dall’attuale versione della CLI di Shopify; verificare i requisiti di installazione della CLI prima di impostare il progetto.

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

Se la versione è precedente, installa Node.js tramite nvm oppure scaricalo da nodejs.org.

2. CLI di Shopify attuale#

Installa la versione corrente della CLI di Shopify e controllala con shopify version. Per l’attuale pacchetto Rust Function (2.0.0 e versioni successive), Shopify documenta CLI 3.85.0 o versioni successive.

3. Toolchain Rust (solo se scriverai funzioni in Rust)#

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

Le Functions in JavaScript non richiedono Rust. Scegli un linguaggio per il team e mantienilo: usarli entrambi aumenta il lavoro di manutenzione.

4. Un negozio di sviluppo#

Accedi alla dashboard Partner e crea un nuovo negozio di sviluppo, oppure usane uno esistente. Distribuirai le Functions in questo negozio prima di portarle in produzione.

Creare la struttura della tua prima Function#

La CLI genera gran parte della struttura iniziale. Da una directory qualsiasi:

# 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

La CLI ti guida con una serie di domande. Per una Function di sconto, scegli:

• Tipo: Function
• Modello: discount (oppure cart_checkout_validation, delivery_customization, payment_customization e così via)
• Linguaggio: Rust o JavaScript
• Nome: per esempio volume-discount-fn

Viene creata la directory extensions/volume-discount-fn/ con questa struttura:

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

I tre file che modificherai più spesso sono .toml (configurazione), .graphql (input) e .rs / .js (logica). Tutto qui.

Tutorial 1: sostituire un Line Item Script (sconto per quantità)#

Supponiamo che il vecchio Script applicasse uno sconto del 10% al subtotale dell’ordine quando il carrello conteneva almeno 5 unità di una determinata collezione. Ecco l’equivalente con una Function.

Passaggio 1.1: la configurazione (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"]

Passaggio 1.2: la query di input (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
  } 
}

Suggerimento: Le Functions vedono solo i dati richiesti dalla query. Mantieni essenziale il GraphQL: ogni campo superfluo che elimini rende l’esecuzione più rapida ed economica.

Passaggio 1.3: la logica (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,
                }],
            },
        )],
    })
} 

Passaggio 1.4: testa, distribuisci e attiva#

# 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 }
  }  
}  

Nel riquadro Variabili di query di GraphiQL, imposta startsAt su un timestamp ISO 8601 futuro. Esamina eventuali campi aggiuntivi obbligatori per la tua versione API prima di eseguire la mutazione.

Ciò crea lo sconto automatico che chiama la funzione distribuita; la funzione sostituisce la logica dello script per questo caso d’uso.

Tutorial 2: sostituire uno Shipping Script (nascondere un metodo oltre una soglia del carrello)#

Uno Script comune dice: «Nascondi la spedizione Express quando il subtotale del carrello supera $500, per evitare costose consegne il giorno successivo sugli ordini più grandi». Ecco la versione con una Delivery Customization Function.

I tutorial 2 e 3 utilizzano i modelli JavaScript attuali. Mantieni i target generati e gli export di src/index.js, imposta api_version = "2026-10" nel file shopify.extension.toml di ogni estensione ed esegui shopify app function typegen nella directory di ciascuna estensione dopo aver sostituito la relativa query di input.

Passaggio 2.1: crea la struttura#

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

Passaggio 2.2: query di input (src/cart_delivery_options_transform_run.graphql)#

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

Passaggio 2.3: logica (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 };
}    

Passaggio 2.4: crea e attiva la personalizzazione della consegna#

Dopo shopify app deploy e l’installazione dell’app nel negozio di destinazione, esegui deliveryCustomizationCreate tramite il client GraphQL Admin autenticato dell’app con l’ambito di accesso write_delivery_customizations. Imposta la variabile functionHandle sul valore di handle dell’estensione in shopify.extension.toml (ad esempio, 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 }
  }
}

Verifica che la risposta restituisca una personalizzazione attivata e nessun userErrors, quindi controlla Impostazioni → Spedizione e consegna → Personalizzazioni della consegna e prova il comportamento del checkout. Il deployment fornisce la Function; questa mutazione crea e attiva la personalizzazione del negozio.

Tutorial 3: sostituire un Payment Script (nascondere il pagamento alla consegna per i clienti B2B)#

Il vecchio Script dice: «Nascondi il pagamento alla consegna per tutti i clienti con il tag “B2B”». Ecco la versione con Payment Customization.

Passaggio 3.1: crea la struttura#

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

Passaggio 3.2: query di input (src/cart_payment_methods_transform_run.graphql)#

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

Passaggio 3.3: logica (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 } }],
  };
}      

Passaggio 3.4: crea e attiva la personalizzazione del pagamento#

Dopo aver distribuito e installato l’app nel negozio di destinazione, esegui paymentCustomizationCreate tramite il client GraphQL Admin autenticato dell’app con l’ambito di accesso write_payment_customizations. Imposta functionHandle sul valore di handle dell’estensione di pagamento in shopify.extension.toml (ad esempio, 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 }
  }
}

Verifica che la risposta contenga una personalizzazione del pagamento attivata senza userErrors. Controllala in Impostazioni → Pagamenti → Personalizzazioni del pagamento, quindi prova il checkout con clienti con e senza il tag B2B.

Già che ci sei: una nota sulle modifiche dopo l’acquisto#

Per le modifiche dopo il pagamento, Revize fornisce ai clienti idonei il servizio self-service prima dell’evasione tramite la pagina Stato dell’ordine o un collegamento all’e-mail di conferma durante la finestra di modifica impostata dal commerciante. Il cambio di prodotto e i prodotti aggiuntivi richiedono Pro; la modifica da parte dello staff è in fase di sviluppo. I clienti esaminano l’eventuale saldo aggiuntivo e pagano tramite il checkout Shopify. Il Gestione ordini Shopify 2026: guida operativa per i team Plus copre il flusso di lavoro post-checkout nativo di Shopify.

Torniamo alla migrazione.

Strategia di test: usare un tag per i clienti#

Utilizza un archivio di sviluppo e dispositivi di input rappresentativi per testare la sostituzione rispetto ai requisiti documentati o ai risultati dei test degli script salvati. Gli script non vengono più eseguiti, quindi un test parallelo in tempo reale di script/funzioni non è più disponibile. Un gate tag cliente può limitare una funzione di test agli account interni mentre ne controlli il comportamento; mantenere il lancio della produzione separato da questi test.

Passaggio 1: aggiungi un tag agli utenti di test#

Nella sezione Customers, aggiungi il tag FN-TESTER a due o tre account interni.

Passaggio 2: fai dipendere l’esecuzione della Function dalla presenza del 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

Passaggio 3: aggiungi hasAnyTag alla query di input#

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

Passaggio 4: verifica nel checkout#

Accedi come utente taggato e verifica i carrelli idonei e non idonei, le combinazioni di sconti e le opzioni di consegna/pagamento. Ripeti con un utente senza tag per confermare che questa funzione non restituisce operazioni. Confrontare i risultati con il comportamento previsto acquisito dalla vecchia logica; includi il checkout degli ospiti nei tuoi test prima di rimuovere il cancello.

Passaggio 5: rivedere l’attivazione della produzione#

Attiva la sostituzione testata tramite la configurazione appropriata di sconto, consegna o pagamento. Registra la versione dell’app distribuita e il piano di rollback, quindi rimuovi le istruzioni script obsolete dalla documentazione del tuo team.

Un flusso di distribuzione che regge nel tempo#

Non continuare a distribuire le Functions dal portatile di uno sviluppatore. Dopo aver migrato uno o due Script, configura una pipeline CI.

Il flusso di lavoro minimo#

# .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 }}

Crea un token di automazione dell’app nella dashboard di sviluppo di Shopify e archivialo come segreto del repository mostrato sopra. L’attuale CLI richiede Node.js 22.12 o versione successiva. Associare il progetto alla configurazione dell’app prima di utilizzare CI; aggiungi i passaggi di test e revisione del rilascio prima della distribuzione. Questo esempio viene distribuito con un push a main, quindi adatta il trigger alla politica di rilascio del tuo team.

Versionamento e ripristino#

shopify app deploy crea una versione salvata. Per tornare a una versione precedente:

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

Con gli Script, per tornare indietro dovevi ricordare il vecchio codice e incollarlo di nuovo. La differenza è notevole.

Gli errori più comuni dei team#

Queste sono le insidie comuni della migrazione da verificare prima di rilasciare una funzione.

1. Convertire ogni Script in una Function separata. Non è necessario. Una sola Function può sostituire tre Script con una logica condizionale più chiara. Esamina tutti gli Script come un unico sistema prima di riscriverli.

2. Confondere gli ambiti dell’app con i dati di input della funzione. Una funzione legge i campi esposti dalla query di input e dai metacampi configurati; non ottiene l’accesso all’Admin API aggiungendo read_customers o read_orders. Aggiungi gli ambiti dell’app solo per operazioni Admin API separate e controlla le regole di input e configurazione dell’API delle funzioni per l’estensione che stai creando.

3. Saltare i test di parità. Confronta la funzione con il vecchio script utilizzando carrelli rappresentativi e casi limite pertinenti prima del rilascio. Utilizza un’implementazione graduale solo quando l’estensione e la configurazione ne supportano una.

4. Saltare il Customizations Report. È il modo migliore per sapere cosa è realmente in esecuzione. Basa la migrazione sul report, non sulla memoria.

5. Inserire nel codice gli ID delle collezioni e i tag dei clienti. Se il merchant deve poter modificare questi valori, usa una configurazione della Function basata sui metafield. La CLI può generare la struttura per questa configurazione: consulta la documentazione Shopify sulla configurazione delle Functions.

Lista di controllo della migrazione#

Utilizza questo elenco di controllo per esaminare lo stato corrente di una migrazione degli script.

Poiché il limite di esecuzione è stato superato, dai la priorità a un controllo del comportamento di pagamento in tempo reale e di qualsiasi lavoro di sostituzione rimanente.

Prossimi passi#

1. Consulta il report sulle personalizzazioni e l’attuale guida alla migrazione di Shopify.
2. Testare le casse di pagamento rilevanti in un development store.
3. Conferma quali funzioni o app pubbliche supportano la logica richiesta nel tuo piano.
4. Verificare ogni sostituzione di produzione e documentarne il proprietario e la configurazione.

Mantieni i test delle regole di pagamento separati dai test di modifica post-acquisto. Per ciascun sistema, registra l’app responsabile, le funzionalità abilitate e il comportamento di evasione/pagamento in modo che le modifiche future abbiano un chiaro proprietario.

Risorse#

• Panoramica di Shopify Functions — documentazione Shopify per sviluppatori
• Migrazione da Shopify Scripts a Functions
• Tutorial: creare una Discount Function
• Riferimento API per Delivery Customization Function
• Riferimento API per Payment Customization Function
• Documentazione di Shopify CLI

Lettura correlata: Statistiche di modifica degli ordini di Shopify (2026) · Come consentire ai clienti di modificare i propri ordini su Shopify (2026)