Shopify SubscriptionContractCalculation API 2026-10

Con Shopify API 2026-10 cambia il modo in cui le app possono creare e modificare i contratti di abbonamento. La nuova SubscriptionContractCalculation API sostituisce il vecchio approccio basato su SubscriptionDraft per le operazioni di create e update, facendo passare i calcoli attraverso lo stesso motore di checkout usato da Shopify.

Per me il punto importante non è il nome dell'oggetto GraphQL, ma il cambio di modello: prima di salvare una modifica posso ottenere un calcolo completo del contratto, controllare totali, consegna, warning e risultato delle Shopify Functions, e solo dopo decidere se fare commit.

Cosa cambia con SubscriptionContractCalculation

Il nuovo flusso è composto da tre passaggi: calculate, poll e commit. L'app invia lo stato desiderato del contratto, Shopify esegue il calcolo in modo asincrono, l'app attende il risultato e infine persiste la modifica con il commit.

Shopify indica questa API come successore di SubscriptionDraft. Il vecchio oggetto resta disponibile, ma non riceverà le nuove capacità introdotte con questo modello. Per le integrazioni che modificano contratti di abbonamento, quindi, la migrazione diventa la strada da pianificare sulla versione API 2026-10.

Perché il nuovo flusso è più interessante del vecchio draft

La differenza pratica è che il calcolo non vive più in un motore separato. Shopify esegue la modifica attraverso il proprio checkout engine e restituisce una preview immutabile prima della persistenza. Questo riduce una classe di problemi che considero particolarmente delicata negli abbonamenti: avere un risultato tecnico della modifica diverso da quello che poi il cliente vede nel ciclo di addebito.

La nuova API consolida inoltre molte operazioni prima distribuite su più mutation. Per creare un contratto si usa subscriptionContractCreateCalculate; per aggiornarlo subscriptionContractUpdateCalculate; per modificare un singolo ciclo di fatturazione subscriptionBillingCycleContractEditCalculate. Il risultato viene poi verificato e salvato tramite subscriptionContractCalculationCommit.

Bundle e Shopify Functions nei contratti ricorrenti

Una delle novità più rilevanti è il supporto ai prodotti bundle nei subscription contract. Il nuovo calcolo può inoltre considerare Shopify Functions come cart transforms e delivery customizations. Non significa che ogni modello di abbonamento diventi automaticamente semplice, ma elimina alcuni limiti strutturali che rendevano più difficile mantenere coerenza tra checkout e rinnovi.

Per chi sviluppa una app di subscription questo cambia anche il modo di progettare i test. Non controllerei soltanto che la mutation termini senza errori: verificherei il risultato calcolato, i warning restituiti, le opzioni di consegna, i totali e poi farei un readback del contratto dopo il commit.

Il flusso calculate → poll → commit

La sequenza che userei è questa:

Calculate. Inviare a Shopify lo stato desiderato del contratto o le sole modifiche previste dall'operazione.
Poll. Attendere che il calcolo asincrono produca un risultato di successo o fallimento. Shopify mette a disposizione anche webhook dedicati per l'esito delle calculation.
Validare. Controllare il risultato calcolato prima di persisterlo: righe, prezzi, sconti, consegna, imposte, eventuali duties e warning.
Commit. Salvare il risultato solo se i controlli applicativi sono superati.
Readback. Rileggere il contratto risultante e verificare il consumer reale, non limitarsi alla risposta positiva della mutation.

Questo approccio è coerente con il metodo che applico alle integrazioni Shopify in generale: una write accettata dall'API non è ancora una verifica del comportamento finale.

Chi deve davvero migrare

Il cambiamento interessa soprattutto le app che creano, aggiornano o modificano i subscription contract tramite SubscriptionDraft. Le app che si limitano a leggere i contratti o a cambiarne lo stato attraverso mutation dedicate, come attivazione o pausa, non sono coinvolte nello stesso modo.

Non confonderei quindi questa novità con una modifica generale all'app nativa Shopify Subscriptions. Se ti interessa il funzionamento degli abbonamenti lato merchant, ho già raccolto i limiti e i casi d'uso nella guida su Shopify Subscriptions e pagamenti ricorrenti. Qui il tema è diverso: l'architettura API per le app che gestiscono i contratti.

Cosa controllerei in una migrazione da SubscriptionDraft

Prima di modificare una integrazione esistente farei un inventario delle mutation oggi usate sul draft e dei dati che l'app assume come definitivi. Poi verificherei almeno quattro aree.

Primo: la gestione dell'asincronia. Il risultato di calculate non va trattato come immediatamente disponibile. Secondo: i mapping dei dati, perché il nuovo oggetto di calculation e la preview devono diventare la fonte da validare prima del commit. Terzo: i test su Functions, bundle e delivery, se fanno parte del modello commerciale. Quarto: il readback post-commit e i casi di failure, che devono lasciare il contratto in uno stato noto e recuperabile.

Per la parte più ampia dell'upgrade consiglio di affiancare questa migrazione alle altre verifiche della versione corrente: ho raccolto il mio controllo generale in Shopify API 2026-10: verifiche prima di aggiornare un'integrazione.

Il punto per merchant e team tecnici

Per un merchant che usa semplicemente una app di abbonamento non c'è una migrazione manuale da fare sull'Admin. La responsabilità tecnica ricade sull'app che gestisce i contratti. Però la qualità di questa migrazione può avere effetti molto concreti: prezzi dei rinnovi, bundle, consegna, sconti e trasformazioni applicate ai cicli ricorrenti.

Per questo eviterei upgrade “alla cieca”. La nuova API offre un modello più robusto proprio perché separa calcolo e persistenza: conviene sfruttare quella separazione per aggiungere controlli, non per ricreare il vecchio flusso con nomi diversi.