API Shopify per la modifica degli ordini: un flusso sicuro dall'avvio alla conferma

Perché le 3 fasi dell’API sono importanti#

La modifica di un ordine è una transazione, non un singolo aggiornamento. Shopify crea una versione calcolata dell’ordine, consente all’app di prepararvi le modifiche e applica quella versione quando l’app le conferma.

Su oltre 10 milioni di ordini nei negozi che usano Revize, circa 1 ordine su 19, pari al 5,2%, è stato modificato dopo il checkout (Revize, 2026). È un volume sufficiente per trattare la modifica degli ordini come un’attività ordinaria, anziché come un’eccezione da affidare all’assistenza.

CalculatedOrder è come una bozza della lista di prelievo del magazzino. Puoi aggiungere e rimuovere righe nella bozza, controllare il risultato e poi applicare una sola versione definitiva.

Il momento in cui avviene la modifica conta quanto la correttezza delle chiamate API. Nei negozi che usano Revize, il tempo mediano tra il checkout e la modifica è di 4,6 minuti (Revize, 2026). Se il prelievo inizia in quell’intervallo, anche un codice tecnicamente corretto può produrre il pacco sbagliato.

Come funziona l’API Shopify per la modifica degli ordini#

Per la Shopify Admin API 2026-07, il flusso prevede orderEditBegin, una o più mutazioni per preparare le modifiche e infine orderEditCommit. I riferimenti delle mutazioni Shopify accettano sia l’ID dell’ordine calcolato sia quello della sessione di modifica per la preparazione e la conferma. Questa guida usa sempre calculatedOrder.id.

1. Chiama orderEditBegin con l’ID dell’ordine Shopify.
2. Salva calculatedOrder.id come $calculatedOrderId.
3. Esegui ogni mutazione di preparazione usando quell’ID.
4. Controlla le righe e i totali dell’ordine calcolato, oltre a ogni array userErrors.
5. Passa lo stesso ID a orderEditCommit.

Shopify documenta questo modello di avvio, preparazione e conferma. L’app richiede l’ambito di accesso write_order_edits.

Una mutazione iniziale minima può richiedere entrambi gli oggetti per la diagnostica, scegliendo poi un solo identificatore per il resto del flusso:

mutation BeginOrderEdit($orderId: ID!) {
  orderEditBegin(id: $orderId) {
    calculatedOrder {
      id
      lineItems(first: 50) {
        nodes {
          id
          quantity
        }
      }
    }
    orderEditSession {
      id
    }
    userErrors {
      field
      message
    }
  }
}

Fermati se userErrors non è vuoto. Una richiesta di rete riuscita dimostra solo che Shopify l’ha ricevuta, non che abbia accettato l’operazione.

La guida alla modifica relativa a questa versione dell’API documenta le operazioni per varianti, quantità, articoli personalizzati, sconti sulle righe d’ordine e righe di spedizione. Controlla il riferimento della mutazione per la versione 2026-07 prima di implementarla e di nuovo prima di cambiare versione dell’API.

Come completare il cambio di una variante#

Per cambiare una variante, aggiungi quella sostitutiva e imposta a zero la quantità della riga originale dell’ordine calcolato nella stessa sessione di modifica. Conferma solo dopo che entrambe le operazioni sono riuscite e il risultato calcolato corrisponde a quanto confermato dal cliente.

Supponiamo che un cliente abbia ordinato una taglia media e abbia bisogno di una taglia grande.

1. Avvia la modifica e salva calculatedOrder.id.
2. Aggiungi la variante grande usando quell’ID:

mutation AddReplacement(
  $calculatedOrderId: ID!
  $variantId: ID!
  $quantity: Int!
) {
  orderEditAddVariant(
    id: $calculatedOrderId
    variantId: $variantId
    quantity: $quantity
  ) {
    calculatedLineItem {
      id
      quantity
    }
    userErrors {
      field
      message
    }
  }
}

3. Trova la taglia media originale nell’ordine calcolato. Usa l’ID della relativa riga calcolata, invece di copiare l’ID di una riga dell’ordine originale senza controllare lo stato calcolato restituito.

4. Imposta a zero la quantità della riga originale:

mutation RemoveOriginal(
  $calculatedOrderId: ID!
  $lineItemId: ID!
) {
  orderEditSetQuantity(
    id: $calculatedOrderId
    lineItemId: $lineItemId
    quantity: 0
  ) {
    calculatedLineItem {
      id
      quantity
    }
    userErrors {
      field
      message
    }
  }
}

5. Interroga di nuovo l’ordine calcolato. Verifica che la variante sostitutiva sia presente, che la quantità della variante originale sia zero e che i totali corrispondano alla conferma del cliente.
6. Conferma usando lo stesso ID dell’ordine calcolato:

mutation CommitOrderEdit(
  $calculatedOrderId: ID!
  $notifyCustomer: Boolean!
  $staffNote: String
) {
  orderEditCommit(
    id: $calculatedOrderId
    notifyCustomer: $notifyCustomer
    staffNote: $staffNote
  ) {
    order {
      id
      updatedAt
    }
    userErrors {
      field
      message
    }
  }
}

Attenzione: non confermare se l’aggiunta è riuscita ma la rimozione no. Trasformeresti il cambio in un articolo aggiuntivo.

Blocca i clic ripetuti sul pulsante di conferma, registra quale fase è stata completata e recupera di nuovo l’ordine prima di confermare se un altro processo potrebbe averlo modificato.

Quale mutazione usare per ogni modifica#

Usa il flusso dell’ordine calcolato per modificare righe d’ordine, quantità, sconti e righe di spedizione. Usa orderUpdate e le mutazioni di annullamento e rimborso solo per le operazioni documentate nei riferimenti delle rispettive versioni.

Il riferimento di orderUpdate per la versione 2026-07 copre attributi come l’email del cliente, l’indirizzo di spedizione, i tag e i metafield, e documenta l’aggiornamento delle note nei suoi esempi. Per modifiche sostanziali, come aggiungere o rimuovere righe d’ordine, cambiare quantità o modificare sconti, rimanda a orderEditBegin.

Le considerazioni di Shopify sulla modifica degli ordini indicano che i codici sconto, gli sconti automatici e gli sconti tramite script non possono essere modificati. Non è possibile nemmeno aggiungere, rimuovere o cambiare gli sconti a livello di ordine. Le mutazioni per gli sconti sulle singole righe d’ordine non eliminano questi limiti.

Dove si ferma l’API Shopify per la modifica degli ordini#

La conferma di una modifica e la gestione del pagamento o del rimborso sono due passaggi distinti. Shopify segnala che una modifica del totale può lasciare un saldo da pagare al cliente o un rimborso da effettuare.

Se il totale aumenta, recupera di nuovo l’ordine confermato e verifica come verrà incassato il saldo prima di avviarne l’evasione. Una risposta riuscita di orderEditCommit non dimostra che il pagamento sia stato completato.

Se il totale diminuisce, la conferma non sostituisce un flusso di rimborso dedicato. Calcola l’importo previsto, chiama l’operazione di rimborso appropriata e controlla la risposta. Una modifica senza differenza di importo non richiede né un incasso né un rimborso, ma richiede comunque una verifica finale dello stato dell’ordine.

Iscriviti al webhook orders/edited di Shopify, poi recupera di nuovo l’ordine prima che un sistema a valle intervenga. I webhook segnalano che occorre leggere il record corrente: non rendono affidabile una copia locale precedente.

Non lasciare che un fornitore di logistica di terze parti, o 3PL, avvii il prelievo di un ordine finché la modifica o la situazione finanziaria non è stata risolta. Verifica la sospensione, la regola sullo stato del pagamento o il segnale di rilascio con il sistema di magazzino che scarica effettivamente gli ordini.

Come diagnosticare gli errori di modifica#

Inizia verificando l’idoneità dell’ordine, gli identificatori, la convalida e le modifiche concorrenti. Registra il nome della mutazione, l’ID dell’ordine Shopify, l’ID di modifica scelto e l’intero array userErrors, senza registrare dati riservati del cliente o del pagamento.

I requisiti di Shopify per la modifica degli ordini indicano che le app richiedono write_order_edits, possono modificare solo le righe d’ordine non evase e non possono modificare gli ordini archiviati o effettuati prima del 1° gennaio 2019. Per impostazione predefinita, le app possono accedere agli ordini degli ultimi 60 giorni; per interrogare ordini più vecchi serve read_all_orders.

Sono regole distinte. read_all_orders amplia l’accesso ai record più vecchi, ma non rende modificabile un ordine archiviato o precedente al 2019.

Non basare il comportamento dell’applicazione su una stringa di errore ipotizzata. Leggi il campo e il messaggio restituiti per la richiesta specifica, poi riproduci l’errore con un ordine di prova controllato.

Scegliere Revize o sviluppare con le API#

Revize è in genere la scelta più adatta quando vuoi consentire ai clienti di modificare gli ordini in autonomia prima dell’evasione; il codice personalizzato è adatto all’orchestrazione interna proprietaria. La scelta è tra un percorso cliente già pronto e la gestione diretta di ogni interfaccia, passaggio e misura di sicurezza per il magazzino.

Il codice personalizzato ha un ruolo preciso quando un merchant ha bisogno di una console proprietaria per lo staff o di un processo di approvazione che coinvolge più sistemi interni. Revize non offre un’API generale per la modifica degli ordini né una coda di approvazione per i merchant.

Le agenzie possono collegare i trigger documentati di Shopify Flow agli eventi di modifica di Revize, usare i tag di modifica e rilascio di Revize nella logica di evasione degli ordini oppure usare la Public Cancellation API per offrire una modalità esterna di annullamento. La Public Cancellation API è disponibile solo con Pro, richiede l’abilitazione da parte dell’assistenza e applica la finestra di modifica, le restrizioni e la politica di rimborso del portale.

Tra le modifiche successive all’acquisto nei negozi che usano Revize, il 92,2% è stato completato dai clienti senza l’intervento di un addetto all’assistenza (Revize, 2026). La guida per le agenzie alla modifica degli ordini dopo l’acquisto tratta le verifiche preliminari da fare prima dell’implementazione.

La disponibilità delle funzionalità varia in base al piano. L’aggiunta e il cambio di prodotti, i rimborsi sotto forma di credito del negozio, il ricalcolo di sconti, spedizione e imposte, il motore di regole, Reverse Unpaid Edits e la Public Cancellation API sono disponibili solo con Pro, come indicato nella documentazione sui piani di Revize.

Installa Revize: Order Editing & Upsell se vuoi offrire ai clienti un modo per modificare gli ordini in autonomia.

Come Revize completa il flusso#

Revize offre ai clienti un flusso di modifica controllato nella pagina di stato dell’ordine Shopify. Il merchant imposta la finestra di modifica, le azioni disponibili, la politica di rimborso e la modalità di elaborazione degli ordini.

Quando una modifica aumenta il totale, Revize mostra Paga ora e reindirizza il cliente al checkout Shopify per pagare soltanto la differenza. Se il totale diminuisce, mostra Rimborso; se resta invariato, mostra Conferma. Shopify esegue il pagamento o il rimborso, come descritto nella documentazione sul flusso cliente di Revize.

Il merchant configura le tempistiche in Order Editing > Order edit window. La guida alla configurazione della finestra di modifica documenta durate preimpostate, durate personalizzate, orari di chiusura programmati e una modalità che consente modifiche fino all’evasione. Quest’ultima modalità non sospende da sola l’evasione dell’ordine.

Con la modalità di elaborazione consigliata, Revize applica una sospensione dell’evasione Shopify durante la finestra di modifica e la rimuove alla chiusura della finestra. I sistemi che ignorano le sospensioni potrebbero richiedere l’alternativa documentata dell’acquisizione manuale del pagamento. In alternativa, un tag di rilascio può dare il via libera a un sistema di evasione configurato per attendere quel tag.

Revize verifica l’inventario aggiornato, tenendo conto della zona di spedizione, prima di consentire al cliente di cambiare variante. La guida alla sospensione dell’evasione degli ordini tratta il lato magazzino del flusso.

Cosa testare questa settimana#

Prova un ordine dal checkout fino all’evasione corretta, includendo i casi di errore. Una mutazione riuscita in un client GraphQL è solo il primo controllo.

1. Crea un ordine di sviluppo o un ordine preliminare rappresentativo.
2. Prova un cambio a parità di prezzo, un aumento e una diminuzione del valore.
3. Controlla userErrors dopo l’avvio, ogni mutazione di preparazione e la conferma.
4. Verifica l’ordine calcolato prima di confermare.
5. Verifica separatamente la gestione dell’incasso e del rimborso.
6. Invia l’ordine modificato attraverso il sistema di evasione effettivo.
7. Prova un ordine archiviato, un ordine più vecchio, tentativi sovrapposti e l’abbandono della modifica.
8. Esamina i limiti della modifica nativa degli ordini Shopify prima di accedere alla produzione.