Shopify Storefront API: Guida Completa per Developer e Merchant

La Storefront API di Shopify è un'API GraphQL pubblica che ti permette di costruire esperienze di acquisto completamente personalizzate, dalle vetrine headless alle app mobile fino alle integrazioni IoT e agenti AI, mentre Shopify gestisce il backend commerce. A differenza dell'Admin API, è progettata per essere chiamata in modo sicuro da browser e client mobile. Se la stai valutando per un progetto in questo momento, la versione stabile attuale è la 2026-04 e una release candidate 2026-07 è già disponibile per i test.

Punti chiave

• La Storefront API è pubblica e sicura da chiamare lato client; l'Admin API deve restare su un server protetto.
• Le mutazioni del carrello (cartCreate, cartLinesAdd, cartBuyerIdentityUpdate) sono le operazioni di scrittura fondamentali che ogni progetto necessita.
• Le versioni API seguono un cadenza trimestrale: 2026-01, 2026-04, 2026-07, 2026-10. La vecchia versione 2024-10 terminerà nel ottobre 2026.
• Hydrogen 2026.4.0 ha reso obbligatorio il proxy della Storefront API e abilitato la modalità consent backend per impostazione predefinita, due breaking change che richiedono un controllo prima dell'aggiornamento.
• A partire da Hydrogen 2026.1.4, ogni vetrina Hydrogen su Oxygen espone automaticamente un endpoint MCP su /api/mcp, rendendola un endpoint commerce pronto per agenti AI senza codice personalizzato.

Cos'è la Shopify Storefront API?

La Storefront API è l'API GraphQL rivolta ai clienti di Shopify. Fornisce agli sviluppatori accesso in lettura a prodotti, collezioni, metaobject e menu, oltre all'accesso in scrittura per le due cose che i buyer fanno veramente: gestire un carrello e autenticarsi come cliente.

Ecco come la documentazione ufficiale di Shopify inquadra il suo modello di accesso: la Storefront API è principalmente di sola lettura, con l'eccezione dell'autenticazione e della gestione del carrello. Questo confine è intenzionale. Puoi recuperare ogni dettaglio del prodotto, costruire un'interfaccia utente di filtri live e creare un flusso di checkout completo senza mai toccare una credenziale segreta.

Il pattern dell'endpoint è semplice:

https://{your-store}.myshopify.com/api/2026-04/graphql.json

Ogni richiesta necessita di un header Shopify-Storefront-Public-Token (o l'equivalente private-token per le chiamate Hydrogen lato server). Il token non è segreto e può essere incorporato nel codice browser o mobile. La tua chiave API Admin e la password, d'altra parte, non devono mai apparire nel codice lato client.

Storefront API vs. Admin API: la vera differenza

Questa è la domanda che ogni merchant e developer si pone per primo, e la risposta è architettonica, non solo un elenco di funzionalità.

L'Admin API ti fornisce accesso completo in lettura e scrittura ai dati del tuo store Shopify: ordini, clienti, prodotti, inventario, fulfillment, analytics e molto altro. La Storefront API manca intenzionalmente di queste funzioni amministrative. Non puoi modificare ordini, gestire l'inventario o accedere a analytics interne tramite essa. Non è una limitazione da aggirare, è il confine di sicurezza che ti consente di incorporare in sicurezza il token in un componente React.

Un errore comune: usare le credenziali dell'Admin API nel codice lato client. Questo espone le credenziali del tuo negozio al pubblico. Mantieni sempre le chiamate dell'Admin API su un server backend protetto. Se hai bisogno di accesso lato client ai dati del negozio, è esattamente per questo che esiste la Storefront API.

Capacità principali: cosa puoi effettivamente costruire

Query di prodotti e collezioni

Recupera titoli dei prodotti, descrizioni, prezzi delle varianti, stato dell'inventario, immagini e metafield. Poiché GraphQL ti consente di richiedere solo i campi di cui hai bisogno, una query di una scheda prodotto può restituire una risposta snella di 3 campi invece di un payload REST ingombrante. La velocità e l'efficienza del ricevere solo i dati che richiedi la rendono ideale per applicazioni sensibili alle prestazioni.

Un importante cambiamento recente: le varianti di prodotto GraphQL ora supportano fino a 2.000 per prodotto, espanse dal limite precedente di 100 varianti. Se vendi prodotti configurabili (taglia x colore x materiale), questo è importante.

Mutazioni del carrello

L'oggetto Cart è il cuore di ogni progetto Storefront API. La superficie di mutazione attuale include:

• cartCreate, crea un nuovo carrello e opzionalmente aggiungi un articolo in una sola chiamata
• cartLinesAdd, aggiungi una o più varianti di prodotto a un carrello esistente
• cartLinesUpdate, aggiorna la quantità sulle righe esistenti (accetta fino a 250 valori per chiamata)
• cartLinesRemove, rimuovi le righe per ID
• cartDiscountCodesUpdate, applica o cancella codici di sconto (sostituisce tutti i codici esistenti con l'elenco fornito)
• cartGiftCardCodesAdd / cartGiftCardCodesRemove, gestisci il riscatto della gift card
• cartBuyerIdentityUpdate, associa un cliente connesso, imposta una posizione aziendale B2B o configura le preferenze di checkout come il metodo di consegna
• cartMetafieldsSet, scrivi metafield arbitrari sul carrello per la logica di checkout personalizzata

Un'aggiunta recente che vale la pena conoscere: il tipo CartLine ora restituisce un campo viewKey, quindi puoi correlare le righe restituite con il view_key inviato a cartLinesUpdate e cartLinesRemove. Utile quando stai creando aggiornamenti UI ottimistici.

Consenso conforme alla privacy

A partire dalla versione della Storefront API 2025-10 e successive, la direttiva @inContext accetta un argomento visitorConsent. Questo ti consente di codificare lo stato del consenso direttamente nella chiamata di creazione del carrello e includerlo automaticamente nell'URL di checkout risultante. Il risultato: flussi di conformità GDPR e CCPA senza uno strato di scrittura di cookie separato.

Metaobject e accesso token-gated

Alcune funzionalità richiedono un'autenticazione basata su token oltre il token di accesso pubblico. Tag di prodotto, metaobject, metafield, menu di navigazione del negozio e dati dei clienti risiedono tutti dietro l'accesso scoped a token. La richiesta di questi scope viene effettuata quando crei l'app Storefront API nell'admin di Shopify.

Versioning delle API: cosa i merchant e gli sviluppatori devono tracciare

La Storefront API di Shopify segue una cadenza di rilascio trimestrale: le versioni sono denominate 2026-01, 2026-04, 2026-07 e 2026-10. Ogni versione è supportata per 12 mesi dopo il rilascio. Le chiamate alle versioni API non supportate comporteranno la delisting delle app o il blocco dell'installazione.

In questo momento le date chiave sono:

• 2026-04 è la versione stabile attuale (più recente).
• 2026-07 è la release candidate, legata all'edizione estiva 2026 di Shopify (nome in codice Compass), che include 65 aggiornamenti di prodotto tra cui breaking change alle strutture di query del carrello e dei prodotti.
• 2024-10 terminerà nel ottobre 2026. Se il tuo progetto headless è ancora su quella versione, hai una finestra temporale limitata per migrare.

I breaking change di 2026-07 influenzano ogni progetto headless, Hydrogen, Next.js Commerce, Nuxt o completamente personalizzato. Shopify fornisce codemods per i progetti Hydrogen per automatizzare le migrazioni di query.

Per i merchant che valutano se agire ora: se stai eseguendo un progetto headless personalizzato su qualsiasi versione anteriore a 2025-04, pianifica un audit della versione con il tuo sviluppatore questo trimestre. Vedi la nostra pagina dei servizi per sviluppatori Shopify per sapere cosa comporta tipicamente un audit della versione.

La connessione con Hydrogen: il proxy della Storefront API è ora obbligatorio

Hydrogen è il framework basato su React di Shopify costruito direttamente sulla Storefront API e nel 2026 la relazione tra i due è diventata significativamente più stretta.

Hydrogen 2026.4.0 (rilasciato il 17 aprile 2026) ha introdotto due breaking change:

1. Il proxy della Storefront API è ora sempre abilitato. L'opzione di configurazione proxyStandardRoutes è stata rimossa. Se un handler di richiesta viene eseguito senza un'istanza storefront nel suo load context, genera un errore di runtime. Qualsiasi setup Hydrogen personalizzato che ha bypassato il proxy deve essere aggiornato.
2. La modalità consent backend è ora l'impostazione predefinita. Hydrogen non si basa più sul cookie _tracking_consent lato client. Il consenso è ora gestito tramite cookie impostati dal server scritti tramite il proxy della Storefront API. I banner di consenso personalizzati che leggono document.cookie per _tracking_consent vedranno un valore vuoto dopo l'aggiornamento.

Il motivo per cui questi due change sono accoppiati: lo scopo intero della modalità consent backend è che le scritture di consenso non possono fallire silenziosamente quando manca un proxy. Il proxy diventare obbligatorio era il prerequisito.

Se esegui un setup Hydrogen personalizzato (qualsiasi progetto che non è uno scheletro pulito di create-hydrogen), verifica i tuoi createRequestHandler e la logica del banner di consenso prima di aggiornare a 2026.4.x.

Il cambiamento più grande nel 2026: la tua vetrina è ora un endpoint per agenti AI

Questo è lo sviluppo che cambia più fondamentalmente il ruolo della Storefront API.

Hydrogen 2026.1.4 ha aggiunto il supporto integrato del proxy Storefront MCP (Model Context Protocol). Ogni negozio Hydrogen su Oxygen ora espone un endpoint MCP su /api/mcp senza alcuna configurazione personalizzata. Cosa significa nella pratica: gli assistenti AI come ChatGPT, Perplexity e gli agenti di shopping personalizzati possono scoprire i tuoi prodotti, gestire i carrelli e guidare i buyer attraverso il checkout usando il linguaggio naturale, il tutto alimentato da dati in tempo reale dalla Storefront API.

Shopify espone tre superfici MCP distinte:

• Catalog MCP, scoperta globale di prodotti tra i merchant Shopify
• Storefront MCP, ricerca specifica del merchant, politiche e FAQ
• Checkout MCP, creazione programmatica del carrello, aggiornamenti e completamento del checkout

La scoperta pubblica dei prodotti attraverso Storefront MCP non richiede autenticazione aggiuntiva. Le operazioni autenticate del carrello utilizzano l'header Shopify-Storefront-Private-Token che la tua app Hydrogen già invia.

Per verificare che il proxy sia attivo nel tuo negozio: accedi a /api/mcp sul tuo deployment Oxygen. Se viene inoltrato al server Storefront MCP di Shopify, sei online.

Per i merchant non ancora su Hydrogen, questo è un motivo concreto per valutare la migrazione. I temi Liquid su CDN di Shopify forniscono prestazioni coerenti ma fisse. Hydrogen su Oxygen fornisce quella baseline di prestazioni più l'integrazione di agenti AI senza degradazione. Il calcolo del ROI per le funzionalità di commerce AI si sta spostando a favore di Hydrogen. Puoi esplorare come sia una migrazione Hydrogen nella nostra pagina dello sviluppatore headless di Shopify.

Checklist pratica per merchant e sviluppatori

Se gestisci una vetrina Hydrogen:

• Conferma di essere sulla Storefront API 2026-04 (la più recente attuale)
• Verifica createRequestHandler per l'opzione proxyStandardRoutes ora rimossa
• Controlla che il tuo banner di consenso legga i cookie impostati dal server, non _tracking_consent
• Testa /api/mcp sul tuo deployment Oxygen per confermare che MCP è attivo
• Inizia a testare la release candidate 2026-07 adesso, non aspettare ottobre

Se gestisci un progetto headless personalizzato (Next.js, Nuxt, ecc.):

• Identifica la tua versione API attuale e mappala rispetto al tramonto di 2024-10 nel ottobre 2026
• Esamina il changelog 2026-07 per i breaking change alle strutture di query del carrello e dei prodotti
• Pianifica codemods o aggiornamenti manuali di query prima del prossimo ciclo di Shopify Editions

Se gestisci un tema Liquid standard:

• La Storefront API è ancora rilevante se usi un'app di terze parti che la chiama lato client
• Verifica che quelle app stiano indirizzando 2026-04 o versioni più recenti
• Considera se le capacità di agenti AI in Hydrogen giustifichino una valutazione di migrazione

La Storefront API non è più solo l'API "Shopify headless". È lo strato di dati che connette il tuo catalogo a ogni superficie che un buyer potrebbe usare: browser, mobile, voce e ora agenti AI. Mantenere la tua versione attuale e il tuo setup Hydrogen allineato con i requisiti di proxy e consent di Shopify è il lavoro di manutenzione che tiene quelle superfici aperte.