Shopify GraphQL Admin API

L'Admin API di Shopify è disponibile sia REST che GraphQL, ma dal 2024 GraphQL è ufficialmente la via raccomandata: la REST viene progressivamente deprecata. GraphQL permette query precise (solo i campi necessari), mutation atomiche, e bulk operations per operazioni massive. In questa guida vediamo l'essenziale.

Perchè GraphQL

GraphQL risolve problemi tipici della REST: over-fetching (ricevi 50 campi quando ne vuoi 3), under-fetching (servono 3 round-trip per dati relazionati), API versioning (campi deprecati notificati nello schema). GraphQL Shopify usa cost-based rate limiting: ogni query ha un costo, hai 1.000 punti/secondo (2.000 su Plus).

Setup

Per chiamare l'API serve: Access token (da custom app o public app installata), endpoint https://your-store.myshopify.com/admin/api/2024-10/graphql.json, header X-Shopify-Access-Token. Versione API: usa 2024-10 (o più recente) per features attuali.

Esempio query

Leggere i primi 10 prodotti con varianti:

query GetProducts {
  products(first: 10) {
    edges {
      node {
        id
        title
        handle
        variants(first: 5) {
          edges {
            node {
              id
              sku
              price
            }
          }
        }
      }
    }
  }
}

Esempio mutation

Creare un prodotto:

mutation CreateProduct {
  productCreate(input: {
    title: "T-Shirt Premium"
    productType: "Abbigliamento"
    vendor: "G Tech Group"
  }) {
    product { id title }
    userErrors { field message }
  }
}

Procedura passo-passo

1. Crea custom app o usa app esistente.
2. Configura scopes: read_products, write_products, ecc.
3. Genera access token (Admin → Apps → Develop apps → Install).
4. Usa GraphiQL su your-store.myshopify.com/admin/api/2024-10/graphql.json o Shopify GraphiQL App.
5. Scrivi e testa query.
6. Implementa in app via fetch o client GraphQL (Apollo, urql).
7. Gestisci rate limit: monitora header X-Shopify-Shop-Api-Call-Limit e retry su 429.
8. Per export massivi usa Bulk operations: mutation bulkOperationRunQuery genera file JSONL.

Bulk operations

Per dataset grandi (>1.000 oggetti), non fare paginazione tradizionale: usa Bulk Operations. mutation { bulkOperationRunQuery(query: "{ products { edges { node { id title } } } }") { bulkOperation { id status } } }. Shopify processa async e fornisce URL JSONL al completamento.

Errori comuni e come risolverli

• Throttle 429: implementa exponential backoff e respect X-Shopify-Shop-Api-Call-Limit header.
• Query troppo costose: rifattorizza in più query piccole o usa bulk operations.
• Scopes mancanti: l'errore parla di permission denied; aggiungi scope e reinstalla app.
• Pagination dimenticata: ricordati di usare after cursor per andare oltre i primi N risultati.

Domande frequenti

D: REST API verrà rimossa?
R: Verrà progressivamente deprecata; alcuni endpoint sono già GraphQL-only.

D: Quanto è il rate limit GraphQL?
R: 1.000 cost points/sec, 2.000 su Plus, ricaricamento 50/sec.

D: Posso usare GraphQL Storefront API per il frontend?
R: Sì, è un'API separata pensata per headless commerce.

Throttling e cost analysis

Ogni query GraphQL ha un costo calcolato (return objects + nesting). Header X-Shopify-API-Call-Limit mostra currentCost/maxAvailable. Strategia: minimizza i campi richiesti, usa first: N con N piccolo, evita nesting profondo. Per export massivi (>1000 oggetti): bulk operations async, ricevi URL JSONL al completamento. Throttle handling: su 429 aspetta retry-after header, implementa exponential backoff (1s, 2s, 4s, 8s).

Storefront API per headless

Oltre Admin API, Shopify ha Storefront API (GraphQL): pubblica, no auth (o customer token), pensata per frontend headless. Use case: app React/Next.js custom, mobile apps, PWA. Limiti: read-only catalog + cart, no inventory write, no order admin. Combinala con Hydrogen (framework Shopify) per headless ottimizzato. La differenza chiave: Admin gestisce, Storefront mostra/vende.

Checklist operativa

Prima di considerare l'argomento implementato correttamente, verifica questa checklist sintetica: configurazione tecnica testata in ambiente di staging o development store, backup attivo prima di ogni modifica critica, documentazione interna aggiornata per il team operativo, training agli operatori che useranno la funzionalità, monitoraggio di metriche chiave (conversion rate, AOV, ticket support) per 30 giorni post-implementazione, revisione legale se l'implementazione tocca aspetti GDPR, fiscali o di pagamento, piano di rollback chiaro nel caso di problemi imprevisti, comunicazione ai clienti se il cambiamento influenza la loro esperienza (es. nuovo checkout, nuovi metodi di pagamento, nuovi tempi di spedizione). Una implementazione tecnica senza queste fasi di accompagnamento spesso non produce i risultati attesi e genera attriti interni o sui clienti.

Risorse utili e community

Per approfondire ulteriormente: la documentazione ufficiale Shopify su shopify.dev e help.shopify.com aggiorna costantemente le guide; il Shopify Community Forum ha thread attivi su quasi ogni argomento con risposte da Shopify Experts; Shopify Partner Academy offre corsi gratuiti per merchant e sviluppatori; YouTube channel ufficiale Shopify pubblica walkthrough delle nuove feature. Per il mercato italiano cerca community come Shopify Italia su Facebook o gruppi LinkedIn dedicati a e-commerce manager italiani: il confronto con altri merchant che vivono problemi simili è una scorciatoia preziosa rispetto a documentazione internazionale generica.

Una buona pratica supplementare è coinvolgere il proprio commercialista o consulente fiscale per qualsiasi configurazione che impatti su fatturazione, IVA o regimi speciali: in Italia ogni semplificazione tecnica deve essere accompagnata da verifica legale puntuale per evitare contestazioni successive. Allo stesso modo, valuta sempre l'impatto SEO di ogni cambiamento: monitora Search Console per le 4-6 settimane successive alla modifica, controlla che il numero di pagine indicizzate non cali e che le query principali continuino a posizionarsi. Per modifiche al tema, mantieni sempre una copia del tema precedente come fallback e documenta i cambiamenti in un changelog interno consultabile dal team. Una governance leggera ma costante è la differenza tra uno store che cresce nel tempo e uno che accumula debito tecnico nascosto.

Hai bisogno di aiuto?

Se vuoi un Shopify ottimizzato dal team di G Tech Group, scrivici tramite il modulo di contatto.