Shopify Storefront API: cosa è cambiato e cosa devi fare

La Shopify Storefront API è un'API GraphQL pubblica che consente agli sviluppatori di creare esperienze di shopping completamente personalizzate su qualsiasi piattaforma, dagli storefront headless alle app mobili e agli agenti AI. Nel 2026 si è mossa più velocemente che mai: la versione 2026-04 è il rilascio stabile attuale, 2026-07 viene lanciata come release candidate oggi (30 giugno 2026) con breaking changes, e la versione 2024-10 viene ritirata in ottobre, offrendo ai team una finestra di cinque mesi per la migrazione. Se il tuo storefront headless non è su una versione supportata in questo momento, il conto alla rovescia è già iniziato.

Punti chiave

• 2026-04 è la versione Storefront API stabile attuale, 2026-07 è la release candidate attiva con breaking changes ai query del carrello e dei prodotti.
• La versione legacy 2024-10 viene ritirata in ottobre 2026, i build personalizzati affrontano costi di bonifica di 8.000 euro, 40.000 se rimandati troppo.
• La versione 2025-10 ha introdotto il parametro visitorConsent sulla direttiva @inContext, codificando il consenso GDPR/privacy direttamente nell'URL del checkout.
• A partire da 2026-07, il Cart emette avvisi PRODUCT_UNAVAILABLE_IN_BUYER_LOCATION e DELIVERY_SELECTED_OPTION_NOT_AVAILABLE in modo che la tua UI possa mostrarli agli acquirenti.
• Gli strumenti Storefront MCP get_cart/update_cart sono deprecati a favore di UCP Cart MCP, con gli strumenti vecchi mantenuti solo fino al 31 agosto 2026.

Il modello di versioning: come funziona il ciclo di rilascio trimestrale di Shopify

Shopify rilascia una nuova versione di Storefront API ogni tre mesi, a gennaio, aprile, luglio e ottobre. Ogni versione stabile è garantita non cambierà durante la sua vita utile supportata, e ogni versione stabile è supportata per un minimo di 12 mesi, il che significa che ci sono almeno nove mesi di sovrapposizione tra due rilasci consecutivi. Quella sovrapposizione è la tua finestra di migrazione.

Ci sono tre tipi di traccia da capire:

• Stabile (ad esempio, 2026-04), sicura per la produzione, compatibilità all'indietro garantita.
• Release candidate (ad esempio, 2026-07), pubblicata lo stesso giorno del nuovo rilascio stabile, disponibile ora per il test ma non consigliata per la produzione.
• Instabile, aggiornata continuamente, le funzioni possono scomparire senza preavviso; solo per lo sviluppo/test.

Un aspetto da considerare: se la tua integrazione mira a una versione inaccessibile (ritirata), Shopify passa silenziosamente in avanti e fornisce la versione stabile accessibile più vecchia. L'intestazione della risposta X-Shopify-API-Version sarà diversa da quella richiesta, questo è il segnale che ti sei allontanato da una versione supportata e sei a rischio di breaking changes silenziosi.

Per le app pubblicate nello Shopify App Store, le conseguenze sono più gravi. Le app che continuano a utilizzare risorse non supportate dopo la scadenza dell'aggiornamento vengono rimosse dall'App Store, con gli utenti bloccati dall'installazione per un minimo di sette giorni.

Confronto tra versioni API: tracce stabile, release candidate e instabile

Cosa è effettivamente cambiato in 2026-04 (la versione stabile attuale)

Scheletro Hydrogen aggiornato a 2026-04. Se hai fissato la tua configurazione Hydrogen a 2026-01, devi aggiornare. Il pacchetto scheletro (skeleton@2026.4.0) ora mira a 2026-04 per tutte le chiamate Storefront API e Customer Account API.

Accesso ai metaobject nelle Shopify Functions. 2026-04 rende possibile alle Shopify Functions eseguire query sui dati dei metaobject direttamente. Se hai logica di sconto o consegna basata su Functions che potrebbe beneficiare dalla lettura delle definizioni dei metaobject in runtime, è ora disponibile.

Limite per i metafield JSON a 128KB. A partire dalla versione API 2026-04, Shopify limita i valori dei metafield JSON a 128KB. Se il tuo storefront legge metafield JSON di grandi dimensioni, controlla i tuoi dati adesso prima che qualsiasi aggiornamento di versione interrompa i payload silenziosamente.

I breaking changes di 2026-07: cosa i build headless devono correggere

Shopify's Summer 2026 Edition (nome in codice Compass) ha spedito 65 aggiornamenti di prodotto. La Storefront API 2026-07 introduce breaking changes alle strutture del carrello e dei query di prodotto che influenzano ogni build headless, Hydrogen, Next.js Commerce, Nuxt, o completamente personalizzato.

Ecco cosa richiede attenzione prima di ottobre:

Segnali di avvertenza del carrello. A partire da 2026-07, l'oggetto Cart emette due nuovi tipi di avvertimento:

• PRODUCT_UNAVAILABLE_IN_BUYER_LOCATION, si attiva quando una linea del carrello contiene un prodotto non disponibile nella posizione dell'acquirente. Ogni linea del carrello interessata restituisce il suo avvertimento, con il target impostato all'ID della Cart Line in modo da poterla mappare sulla linea corretta nella tua UI.
• DELIVERY_SELECTED_OPTION_NOT_AVAILABLE, si attiva quando l'opzione di consegna scelta dall'acquirente diventa non disponibile (ad esempio, dopo un cambio di indirizzo del carrello). In precedenza, il sistema cambiava silenziosamente le opzioni di consegna senza notifica all'acquirente. Ora puoi rilevarlo programmaticamente e invitare l'acquirente a scegliere di nuovo.

Rimozione enum metaobject. Gli enum di controllo di accesso deprecati PRIVATE e PUBLIC_READ sulle definizioni dei metaobject vengono rimossi in 2026-07. Se la tua app o storefront fa riferimento a questi valori enum, aggiorna al modello di controllo di accesso attuale prima che il rilascio diventi stabile.

Ristrutturazione del campo sconto. 2026-07 ristruttura i campi relativi agli sconti sul Cart. Se il tuo storefront ha qualche logica personalizzata di visualizzazione degli sconti o dei coupon, inizia il refactoring rispetto alla release candidate adesso. Gli utenti di Hydrogen ricevono codemods per la maggior parte dei rinomi di campi strutturali; i framework personalizzati sono per conto loro, e le stime di bonifica si aggirano tra gli 8.000 e i 40.000 euro a seconda della complessità dello storefront.

La scadenza di ottobre 2026 è ferma. La versione API 2024-10 viene ritirata in ottobre 2026. Cinque mesi sembrano confortevoli, non lo sono, una volta che consideri i deploy di staging, il testing di regressione, e il fatto che la logica del carrello è tipicamente la parte più fragile di qualsiasi stack headless. Inizia a testare rispetto alla release candidate 2026-07 adesso.

Checkout conformi alla privacy con @inContext visitorConsent

Questo è arrivato in 2025-10 e rimane uno degli aggiunte più utili della Storefront API negli ultimi tempi. La direttiva @inContext ora accetta un parametro visitorConsent, permettendo agli sviluppatori di passare le preferenze di consenso dell'acquirente, analytics, preferences, marketing, e vendita di dati, alle operazioni del carrello.

La meccanica è pulita: codifichi il consenso nella mutazione cartCreate o cartBuyerIdentityUpdate in questo modo:

@inContext(visitorConsent: {
  analytics: true,
  preferences: true,
  marketing: false,
  saleOfData: false
})

Le informazioni di consenso vengono automaticamente codificate e incluse nel checkoutUrl risultante, garantendo la conformità alla privacy durante l'intero processo di checkout. Shopify legge il parametro _cs che aggiunge all'URL durante il checkout, non strapparlo.

Questo è importante per il GDPR e regimi simili. Gli storefront headless che in precedenza non avevano un modo pulito per propagare il consenso da un banner di cookie fino al checkout ora hanno un meccanismo first-party integrato nell'API stessa. Non c'è scusa per un build headless moderno di non implementare questo.

Limiti di velocità: la nuova realtà di bot e agenti

Shopify ora applica limiti di velocità più ristretti ai bot e agli agenti che accedono alla Storefront API e alle pagine degli store online ospitati da Shopify. I bot e gli agenti che non firmano le loro richieste sono soggetti ai limiti più ristretti; per qualificarsi per limiti di velocità più alti, gli operatori dovrebbero firmare le richieste utilizzando Web Bot Auth.

Per commercianti e sviluppatori legittimi, l'implicazione pratica è doppia:

1. Se gestisci un crawler personalizzato, aggregatore di prezzi, o agente di shopping AI che colpisce gli endpoint della Storefront API, firma le tue richieste o aspettati la limitazione.
2. Se stai costruendo un'integrazione Storefront MCP (vedi la sezione successiva), assicurati che il tuo profilo di agente sia registrato correttamente in modo che riceva il livello di accesso appropriato.

Nota che la Storefront API non ha alcun limite di velocità applicato al numero di richieste legittime degli acquirenti, è progettata per scalare attraverso i flash sale senza che tu gestisca la concorrenza. I nuovi limiti mirano specificamente al traffico di bot malevoli o non identificati.

Agentic commerce: Storefront API incontra UCP e MCP

Questo è il cambiamento strutturalmente più significativo nel ruolo della Storefront API nel 2026. L'API non è più solo la spina dorsale per gli storefront headless rivolti all'uomo. Ora è il punto di ingresso per gli agenti AI.

Shopify ha co-sviluppato l'Universal Commerce Protocol (UCP) con Google come standard aperto per il modo in cui gli agenti AI effettuano transazioni con i commercianti. UCP copre l'intero percorso commerciale dalla scoperta attraverso i carrelli al checkout, e ha ampio supporto industriale incluso Amazon, Meta, Microsoft, Salesforce, Stripe, e Wayfair.

Per gli sviluppatori, la superficie di implementazione concreta è il server Storefront MCP. Ogni negozio Shopify ha il suo endpoint MCP che espone funzioni di storefront tra cui la ricerca di prodotti, le operazioni del carrello, e le domande sulle politiche. Gli strumenti search_catalog, lookup_catalog, e get_product rispettano la specifica UCP.

Nota critica di migrazione: Gli strumenti del carrello Storefront MCP legacy (get_cart e update_cart) sono stati deprecati a favore di UCP Cart MCP. Gli strumenti deprecati saranno mantenuti fino al 31 agosto 2026, quella è la stessa trimestre del tramonto dell'API 2024-10. Due migrazioni convergono sulla stessa scadenza autunnale.

Se stai costruendo un agente con marchio o un'esperienza di shopping AI personalizzata, l'architettura è semplice:

• Usa Storefront MCP per la ricerca del catalogo e il recupero dei dettagli del prodotto.
• Usa UCP Cart MCP per le operazioni del carrello (aggiungi, aggiorna, leggi gli elementi della linea).
• Usa Checkout Kit (o l'imminente Checkout MCP, attualmente in anteprima partner) per il trasferimento dei pagamenti.

Per i commercianti che non stanno costruendo agenti personalizzati, l'azione pratica è più semplice: attiva i canali AI che desideri vendere nell'admin di Shopify tramite Agentic Storefronts, e Shopify gestisce il lavoro del protocollo. ChatGPT, Google AI Mode, Perplexity, e Microsoft Copilot sono tutti raggiungibili attraverso una singola configurazione admin.

Autenticazione e token di accesso: cosa cambia a gennaio 2027

Un elemento che cade al di fuori del ciclo della versione API 2026 ma influenza direttamente le integrazioni della Storefront API: a partire dal 1 gennaio 2027, tutte le app pubbliche devono utilizzare token di accesso offline in scadenza per le chiamate Admin API. Questo è un cambiamento Admin API, non un cambiamento alla Storefront API, ma molte integrazioni utilizzano entrambe insieme, se il tuo build headless si affida a un token Admin API di lunga durata per le operazioni di backend (sincronizzazione dell'inventario, gestione degli ordini, scritture di metafield), devi pianificare quella migrazione insieme al tuo aggiornamento della versione Storefront API.

La tua checklist di migrazione per il resto del 2026

Ecco l'elenco di azioni sequenziate, ordinato per urgenza:

1. Controlla la tua versione attualmente fissata. Apri la configurazione di Hydrogen o gli intestazioni del query GraphQL. Qualsiasi cosa più vecchia di 2025-07 ha bisogno di attenzione immediata.
2. Testa rispetto a 2026-07 RC. Avvia un ambiente di staging rispetto alla release candidate. Concentrati sulle mutazioni del carrello e qualsiasi logica personalizzata di visualizzazione degli sconti.
3. Implementa visitorConsent su @inContext. Se il tuo build headless non propaghi ancora il consenso dei cookie attraverso al checkoutUrl, aggiungilo adesso. Richiede la versione API 2025-10 o successiva.
4. Sostituisci gli enum metaobject deprecati. Rimuovi qualsiasi riferimento PRIVATE o PUBLIC_READ prima che 2026-07 diventi stabile il 1 luglio.
5. Migra dai tool del carrello Storefront MCP a UCP Cart MCP. Scadenza: 31 agosto 2026.
6. Controlla i metafield JSON superiori a 128KB. Richiesto prima di qualsiasi aggiornamento 2026-04+.
7. Registra una firma Web Bot Auth se gestisci un bot o un agente che colpisce gli endpoint della Storefront API.

Se hai bisogno di aiuto pratico per pianificare o eseguire una di queste migrazioni, i servizi di sviluppatore Shopify che offro coprono gli aggiornamenti di versione, le revisioni dell'architettura headless, e gli audit di performance della Storefront API.