In questa pagina
Shopify ha aggiunto queste API nella versione 2026-10. Adottale quando la tua integrazione per la gestione o l’evasione degli ordini deve visualizzare la richiesta di annullamento in attesa di un cliente prima che il merchant la elabori.
Limita gli invii alla rimozione di unità non evase
La modifica supportata è la rimozione. Nella versione 2026-10, l’input lineItems di orderRequestEdit contiene solo removals, ciascuna con un lineItemId e la quantity richiesta. Sono consentite quantità parziali. Non esiste un tipo di richiesta per aggiunte o cambi di variante, né per modifiche a indirizzo, spedizione o sconti.
Nel flusso nativo degli account cliente, i clienti selezionano Cancel items su un ordine idoneo. Gli account cliente legacy non sono supportati. I requisiti di configurazione di Shopify descrivono l’attivazione in Settings > Customer accounts. Usa la guida alla migrazione degli account cliente se il negozio usa ancora gli account legacy.
Leggi Order.requestedEditInformation quando crei l’interfaccia per il cliente. Il suo oggetto di idoneità espone hasEditableLineItems, editableLineItems e ineligibleLineItems. Mostra le quantità idonee in base a quella risposta. Non presumere che ogni unità non evasa sia disponibile per una nuova richiesta.
Le richieste self-service native si applicano anche agli ordini B2B. L’elaborazione di una richiesta per un ordine in abbonamento lascia attivo il contratto di abbonamento. L’attivazione per singolo mercato richiede Advanced o Plus e l’accesso alle impostazioni delle azioni sugli ordini in accesso anticipato nell’editor del checkout e degli account. I negozi senza questa opzione attivano le richieste su tutti i mercati.
Collega le API e configura le autorizzazioni
Usa la documentazione della versione 2026-10. La risorsa della richiesta è RequestedOrderEdit. La sua enumerazione degli stati contiene REQUESTED, RESOLVED e DECLINED. REQUESTED significa che è in attesa un’azione del merchant. Non esiste uno stato APPROVED.
| Chiamante | Operazione | Scopo |
|---|---|---|
| Admin API | requestedOrderEditCreate |
Creare una richiesta per conto di un cliente |
| Admin API | requestedOrderEditResolve |
Contrassegnare una richiesta come risolta |
| Admin API | requestedOrderEditDecline |
Rifiutare una richiesta |
| Customer Account API | orderRequestEdit |
Inviare la richiesta del cliente |
| Entrambe le API | requestedOrderEditCalculate |
Visualizzare un’anteprima del risultato finanziario |
Per le query Admin, richiedi read_orders. Le tre mutation Admin richiedono write_orders e l’autorizzazione dello staff edit_orders, come specificato nella documentazione di creazione. Il flusso di modifica calcolata del merchant richiede separatamente write_order_edits.
Per la mutation del cliente, richiedi customer_write_pre_authenticated. L’utente deve anche disporre dell’accesso customer_write_orders o di un accesso preautenticato all’ordine. Per la query di anteprima del cliente, l’app deve disporre di customer_read_pre_authenticated e l’utente deve avere l’accesso customer_read_orders o un accesso preautenticato a quello specifico ordine prima che tu offra l’anteprima. La lettura di OrderRequestedEditInformation richiede customer_read_orders.
Usa @idempotent su orderRequestEdit e riutilizza la chiave quando ritenti lo stesso invio. Shopify restituisce la richiesta originale invece di crearne un’altra.
Sospendi l’evasione mentre il merchant esamina la richiesta
Per una richiesta in attesa non è documentata una sospensione automatica. Il changelog di Shopify descrive la sospensione dell’evasione come un’attività che un’app può eseguire sugli ordini con stato REQUESTED.
Sottoscrivi i tre topic webhook delle richieste: requested_order_edit/created, requested_order_edit/resolved e requested_order_edit/declined. Ciascuno richiede almeno uno tra read_orders, read_marketplace_orders o read_buyer_membership_orders. I payload identificano l’ordine e le rimozioni richieste, incluse quantity e resolved_quantity. Gli stati nei webhook di esempio sono in minuscolo. I valori delle enumerazioni GraphQL sono in maiuscolo.
Se il merchant vuole sospendere il prelievo durante l’esame della richiesta, implementa questa sequenza nella tua integrazione:
- Su
/created, recupera l’ordine e la richiesta attuali. Registra l’ID della richiesta associandolo all’ordine nel magazzino. - Applica la sospensione dell’evasione o il meccanismo di arresto del magazzino gestito dalla tua integrazione. Se il magazzino ha già importato l’ordine, richiedi la sua conferma che il prelievo si sia fermato per le unità richieste.
- Su
/resolvedo/declined, recupera le richieste rimanenti dell’ordine e le quantità attuali. Rimuovi la sospensione della tua integrazione solo dopo che le richieste in attesa e le eventuali operazioni di rimborso necessarie sono state completate.
Controlla ogni richiesta. Un ordine può avere più richieste e displayRequestedEditStatus = REQUESTED significa che almeno una richiede ancora un’azione del merchant. Non rimuovere la sospensione in seguito a un solo evento /resolved.
Concorda la conferma dell’arresto prima di abilitare il rilascio automatico. La guida all’integrazione della sospensione dell’evasione tratta i controlli a valle.
Elabora la rimozione prima di chiudere la richiesta
Nel pannello di controllo Shopify, filtra Orders per Customer request. La richiesta appare in un banner sull’ordine. Chi esamina le richieste deve avere l’autorizzazione Orders.
Per un ordine pagato, Remove items apre la pagina di rimborso con gli articoli richiesti selezionati. Seleziona gli articoli da rimborsare, controlla l’importo e le opzioni di reintegro delle scorte, poi fai clic su Refund. Shopify contrassegna la richiesta come risolta. Per gli ordini non pagati, Remove items apre invece la pagina per il reintegro delle scorte.
La risoluzione chiude la registrazione della richiesta. La documentazione di requestedOrderEditResolve descrive l’operazione come il contrassegno della richiesta come completata e il suo unico input è l’id della richiesta, senza campi per quantità, rimborso o reintegro delle scorte. Rimuovi e rimborsa le unità separatamente e conserva entrambe le operazioni nel registro di esecuzione della tua implementazione.
Usa requestedOrderEditCalculate per visualizzare un’anteprima del risultato finanziario della rimozione richiesta prima dell’invio. Restituisce financialSummary e le righe d’ordine calcolate. Un’anteprima non movimenta denaro. La nostra guida alle API per la modifica degli ordini tratta il flusso esistente di avvio, preparazione e conferma e le relative operazioni separate per regolare i pagamenti.
Per rifiutare la richiesta, chiama requestedOrderEditDecline. Il suo declineNote facoltativo è un messaggio di notifica al cliente con un massimo di 500 caratteri. Nel pannello di controllo Shopify, Manage request > Mark as resolved chiude invece la richiesta senza modificare l’ordine né inviare un’email al cliente. Rifiuta la richiesta quando il merchant non accetta la rimozione. Risolvila solo dopo che le unità sono state rimosse e rimborsate, oppure quando la richiesta è stata gestita in un altro modo.
Verifica le transizioni non documentate prima del rilascio
Nel pannello di controllo Shopify, il rimborso degli articoli richiesti risolve la richiesta, così come l’annullamento dell’ordine, mentre la rimozione degli articoli con rimborso successivo la lascia aperta. Shopify non documenta se refundCreate o un orderEditCommit che rimuove le unità richieste risolvano la richiesta tramite API. Verifica su un negozio di sviluppo se il tuo flusso API si comporta come il pannello di controllo prima di farvi affidamento.
Crea una richiesta per una parte di una riga non evasa, poi elabora quella quantità tramite il flusso di rimborso o modifica previsto senza chiamare requestedOrderEditResolve. Controlla lo stato risultante della richiesta e resolvedQuantity, insieme alle unità rimanenti dell’ordine e alla transazione di rimborso. Registra quali webhook delle richieste arrivano.
Crea un’altra richiesta per unità idonee diverse sullo stesso ordine e metti alla prova il gestore del rilascio mentre una richiesta è ancora in attesa. Mantieni bloccato l’ordine in magazzino finché il merchant ha ancora una richiesta da esaminare. Se la rimozione o il rimborso non riescono, mostra al merchant un’eccezione visibile e mantieni l’ordine bloccato.
Per il recupero, esegui una query orders paginata usando il filtro requested_order_edit_status:requested. Recupera la connessione requestedOrderEdits di ogni ordine corrispondente e riconciliala con le tue registrazioni delle richieste. Riconcilia anche, per ID, gli ordini che la tua integrazione tiene in sospeso, perché un ordine la cui ultima richiesta si è chiusa mentre un webhook è andato perso non compare più in quella ricerca. Imposta l’intervallo di scansione in base alle regole di rilascio del magazzino.
Scegli chi esegue la modifica
Gestisci le aggiunte al di fuori dell’API per le richieste dei clienti. Il flusso di modifica del merchant di Shopify consente di aggiungere prodotti prima dell’evasione.
Per i clienti che hanno bisogno di cambi di variante, correzioni dell’indirizzo o aggiunte di articoli entro una finestra di modifica stabilita dal merchant, i negozi usano un’app di modifica self-service come Revize. La sua impostazione Hold orders, sotto Fulfillment while editing, sospende l’evasione mentre la finestra di modifica con limite di tempo è aperta, poi la rilascia secondo i tempi di rilascio e le condizioni di pagamento configurati. Con la scadenza Until fulfillment, Revize non applica alcuna sospensione.
| Modifica richiesta dal cliente | Modifica del merchant | Revize (app self-service) | |
|---|---|---|---|
| Chi la avvia | Il cliente negli account cliente o tramite orderRequestEdit. Un’app può creare una richiesta per il cliente |
Lo staff del merchant o un’app che usa le API per la modifica degli ordini | Il cliente sulla pagina di stato dell’ordine di Shopify |
| Chi la approva | Il merchant o un’app esamina ed elabora o rifiuta la richiesta | Lo staff o un’app esegue la modifica | Il merchant imposta in anticipo le azioni consentite. L’annullamento è automatico se idoneo |
| Che cosa può cambiare | Rimozione di unità non evase, incluse quantità parziali. L’invio non modifica nulla | Prodotti, quantità, spese di spedizione, sconti manuali entro i limiti delle modifiche native | Modifiche a varianti e quantità, indirizzo di spedizione, aggiunta di prodotti. L’aggiunta di prodotti richiede Pro |
| Pagamento | La creazione e la risoluzione non emettono rimborsi. L’elaborazione della rimozione richiede una decisione sul rimborso | Se il totale aumenta, è possibile inviare una fattura aggiornata. Se diminuisce, è possibile emettere un rimborso | Pay now, Refund o Confirm, a seconda che il totale aumenti, diminuisca o resti invariato. Shopify esegue il pagamento o il rimborso; Pay now riscuote solo la differenza |
| Evasione | Solo unità non evase. Nessuna sospensione automatica documentata | Modifiche alle quantità e rimozioni: solo per le righe d’ordine non evase. Gli sconti manuali possono essere modificati anche sugli articoli già evasi | Prima dell’evasione, entro la finestra stabilita dal merchant. La modalità Hold orders sospende l’evasione |
Configura Fulfillment while editing insieme al magazzino prima di aprire il flusso di modifica per i clienti. Per le istruzioni di annullamento rivolte ai clienti, indirizzali alla guida all’annullamento.
Domande frequenti
La nostra richiesta è RESOLVED, ma le unità sono ancora presenti. L’API non ha funzionato?
Lo stato da solo non dimostra la rimozione. requestedOrderEditResolve contrassegna la richiesta come completata e accetta solo l’id della richiesta, senza campi per quantità, rimborso o reintegro delle scorte. L’assistenza dovrebbe controllare l’ordine effettivo e la registrazione del rimborso prima di dire al cliente che l’elaborazione è terminata.
Il cliente può richiedere un cambio di taglia tramite queste API?
No. Gli input delle richieste della versione 2026-10 supportano solo la rimozione di unità non evase. Gestisci il cambio di taglia con il flusso del negozio per la modifica da parte del merchant o per la modifica self-service da parte dei clienti.
Un webhook di risoluzione significa che tutte le richieste su quell’ordine sono chiuse?
No. Recupera requestedOrderEdits o controlla displayRequestedEditStatus prima di sbloccare l’ordine in magazzino. Un valore REQUESTED a livello di ordine significa che almeno una richiesta attende ancora un’azione del merchant.
Dobbiamo mantenere le sottoscrizioni agli annullamenti degli ordini di evasione?
Mantienile se la tua integrazione con il servizio di evasione ne ha bisogno. I topic fulfillment_orders/cancellation_request_* riguardano le richieste di un merchant o di un’app a un servizio di evasione. Le modifiche richieste dai clienti usano requested_order_edit/* e richiedono una gestione dedicata.