---
title: "Shopify Storefront API GraphQL : le guide complet"
description: "Guide technique complet de la Shopify Storefront API avec GraphQL. Queries, mutations, authentication, cart, metafields et architecture headless."
date: "2026-03-12"
author: "Bastien Allain"
category: "E-commerce"
tags: ["shopify", "graphql", "api", "storefront", "headless"]
keywords: ["shopify", "graphql", "api", "storefront", "headless"]
image: "/blog/category-ecommerce.webp"
published: true
locale: "fr"
translationKey: "shopify-storefront-api-guide"
imageAlt: "Shopify Storefront API GraphQL : le guide complet"
lastmod: "2026-03-12"
authorImage: "/authors/bastien-allain.webp"
authorTwitter: ""
isFamilyFriendly: true
---

La **Shopify Storefront API** est une API GraphQL publique qui permet aux developpeurs de construire des experiences d'achat sur mesure en dehors du theme Liquid classique. Elle expose les objets fondamentaux `Product`, `Collection`, `Cart` et `Customer` en lecture, ainsi que des mutations pour la gestion du panier et l'identite client (customer identity).

Contrairement a l'Admin API, reservee a la gestion back-office, la Storefront API est concue pour alimenter directement les interfaces utilisateur :

- Storefronts headless avec **Next.js** ou **Hydrogen**
- Applications mobiles natives (iOS, Android)
- Progressive Web Apps (PWA)
- Bornes interactives en point de vente
- Interfaces vocales et IoT

Son adoption s'impose en 2026 comme le standard pour les marques e-commerce qui exigent des performances et une flexibilite que les architectures monolithiques ne peuvent plus offrir. Dans un ecosysteme de **composable commerce**, la Storefront API devient le socle technique du **headless commerce** sur Shopify, permettant de dissocier totalement le front-end du back-end transactionnel et de s'inscrire dans une architecture Jamstack moderne. Cette approche est particulierement repandue sur les boutiques **Shopify Plus** qui gerent des volumes de trafic eleves et des catalogues internationalises.

Pour une vue d'ensemble du headless commerce sur Shopify, consultez notre [guide complet du headless Shopify](/blog/e-commerce/shopify-headless-guide-complet).

## Pourquoi Shopify a choisi GraphQL pour sa Storefront API

### Les limites du REST pour le commerce headless

Les API REST traditionnelles imposent des endpoints fixes qui retournent des structures de donnees predefinies. Pour afficher une page produit complete, un client REST doit enchainer plusieurs appels sequentiels :

1. `/products/{id}` pour les informations de base (titre, description, statut)
2. `/products/{id}/variants` pour les variantes et leurs prix
3. `/products/{id}/images` pour les visuels
4. `/products/{id}/metafields` pour les donnees personnalisees

Chaque requete supplementaire ajoute de la latence et degrade les Core Web Vitals. La cascade de requetes (request waterfall) impacte negativement le **Largest Contentful Paint (LCP)** en retardant le chargement des images produit, et le **Interaction to Next Paint (INP)** lorsque les donnees bloquent l'interactivite. Dans un contexte headless ou chaque milliseconde compte pour le taux de conversion, cette approche devient un goulot d'etranglement.

### GraphQL : une requete, une reponse precise

GraphQL resout ce probleme fondamental. Grace au **schema fortement type** (strongly typed schema) de la Storefront API -- versionne trimestriellement par Shopify (ex. `2026-01`) -- une seule requete suffit pour recuperer exactement les donnees necessaires. Les principaux avantages :

- **Elimination du sur-fetching** : seuls les champs demandes sont retournes, aucune donnee inutile n'est transferee
- **Elimination du sous-fetching** : toutes les donnees necessaires arrivent en une seule requete, sans appels supplementaires
- **Schema auto-documente** : le schema GraphQL sert de contrat d'API explorable via des outils comme GraphiQL
- **Typage fort** : les erreurs de structure sont detectees avant l'execution, cote client comme cote serveur

Concretement, une **query** GraphQL unique peut retourner simultanement :

- Les details d'un produit (titre, description, handle)
- Ses **product variants** avec prix localises via l'**international pricing**
- Les images optimisees avec dimensions
- Les **metafields** personnalises
- La disponibilite en stock par emplacement

Voici une requete typique pour une page produit avec prix internationalises :

```graphql
query ProductPage($handle: String!, $country: CountryCode!)
  @inContext(country: $country) {
  productByHandle(handle: $handle) {
    title
    descriptionHtml
    variants(first: 10) {
      edges {
        node {
          priceV2 { amount currencyCode }
          availableForSale
        }
      }
    }
    metafields(identifiers: [{ namespace: "custom", key: "specs" }]) {
      value
      type
    }
  }
}
```

La directive `@inContext` permet de contextualiser les prix selon le pays de l'acheteur, une fonctionnalite native de la Storefront API pour le commerce international.

**Queries : pour la lecture de donnees.** Les queries permettent de recuperer des informations sans modifier l'etat de la boutique. C'est le mecanisme utilise pour afficher les catalogues, les pages produit et les collections.

**Mutations : pour l'ecriture de donnees.** Les mutations modifient l'etat du storefront. Les mutations les plus courantes de la Storefront API sont `cartCreate`, `cartLinesAdd`, `cartLinesUpdate` et `customerAccessTokenCreate`.

**Nuance importante** : cette efficacite a une contrepartie. Contrairement au REST ou le cache HTTP natif (ETags, Cache-Control) fonctionne par endpoint, le caching des reponses GraphQL necessite une strategie dediee. Cote client, des bibliotheques comme Apollo Client ou urql normalisent le cache. Cote serveur, les **persisted queries** combinees a un CDN (Cloudflare, Fastly) permettent de mettre en cache les reponses au niveau edge.

## Storefront API vs Admin API : comparaison technique

Le choix entre la Storefront API et l'Admin API depend du cas d'usage. Voici les differences fondamentales :

### Cas d'usage et permissions

| Critere | Storefront API | Admin API |
|---|---|---|
| **Audience** | Applications client-side, storefronts publics | Applications back-office, automatisations serveur |
| **Acces** | Lecture produits/collections + ecriture panier/client | Lecture/ecriture complete sur toutes les ressources |
| **Token** | Public access token (exposable cote client) | Private access token (secret, serveur uniquement) |
| **Rate limits** | Par IP acheteur (scalable) | Par boutique (bucket de points) |
| **IDs** | Base64 encodes (`Z2lkOi8v...`) | Global IDs (`gid://shopify/Product/123`) |

### Quand utiliser l'une ou l'autre

**Utilisez la Storefront API** pour toute interface destinee aux acheteurs : affichage du catalogue, page produit, gestion du panier, recherche et filtrage, authentification client.

**Utilisez l'Admin API** pour les operations back-office : creation de produits, gestion des commandes, synchronisation d'inventaire, webhooks et automatisations.

Dans une architecture headless typique, les deux API coexistent. Le front-end consomme la Storefront API pour l'experience d'achat, tandis que des services back-end utilisent l'Admin API pour la gestion operationnelle. Decouvrez comment structurer cette architecture dans notre [service de developpement Shopify headless](/services/builds/shopify-headless).

## Demarrage rapide : votre premiere requete en 5 minutes

### Generer vos identifiants d'acces

Pour acceder a la Storefront API, installez le canal de vente **Headless** depuis l'App Store Shopify :

1. Dans l'admin Shopify, installez le canal **Headless**
2. Cliquez sur **Create storefront** pour generer les tokens d'acces
3. Notez le **private access token** (pour les requetes serveur) et le **public access token** (pour les requetes client-side)

Chaque boutique peut disposer de 100 storefronts actifs maximum, chacun avec ses propres tokens et permissions.

### Authentication : public access token vs delegated access token

La Storefront API propose deux modes d'authentification :

**Public access token** : utilisable directement dans le navigateur ou une application mobile. Ce token donne acces aux donnees publiques de la boutique (produits, collections, prix). Il est transmis via le header `X-Shopify-Storefront-Access-Token`.

```javascript
const headers = {
  "Content-Type": "application/json",
  "X-Shopify-Storefront-Access-Token": "votre-public-token"
};
```

**Delegated access token** : genere cote serveur pour un client authentifie. Il donne acces a des donnees personnalisees (historique de commandes, adresses) en plus des donnees publiques. Ce token est obtenu via la mutation `customerAccessTokenCreate` apres authentification du client.

La difference de securite est fondamentale : le public access token peut etre expose dans le code front-end sans risque, tandis que le delegated access token doit rester cote serveur pour proteger les donnees personnelles du client.

### Configurer un client GraphQL

Vous pouvez interroger la Storefront API avec n'importe quel client HTTP. Voici un exemple avec un simple `fetch` en JavaScript :

```javascript
const SHOPIFY_STORE = "votre-boutique.myshopify.com";
const API_VERSION = "2026-01";
const STOREFRONT_TOKEN = "votre-public-token";

async function storefrontQuery(query, variables = {}) {
  const response = await fetch(
    `https://${SHOPIFY_STORE}/api/${API_VERSION}/graphql.json`,
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "X-Shopify-Storefront-Access-Token": STOREFRONT_TOKEN,
      },
      body: JSON.stringify({ query, variables }),
    }
  );
  const { data, errors } = await response.json();
  if (errors) throw new Error(errors.map((e) => e.message).join(", "));
  return data;
}
```

Pour des projets en production, privilegiez un client GraphQL dedie comme **Apollo Client** (cache normalise, gestion d'erreurs avancee) ou **urql** (leger, extensible via des exchanges).

### Executer votre premiere query

Testez votre configuration en recuperant les informations de la boutique :

```graphql
query ShopInfo {
  shop {
    name
    primaryDomain {
      url
    }
    paymentSettings {
      currencyCode
    }
  }
}
```

Si la reponse contient le nom de votre boutique, votre configuration est operationnelle.

## Maitriser les operations GraphQL de la Storefront API

### Queries : recuperer les donnees de la boutique

#### Lister les produits avec variantes, prix et images

La query suivante recupere les 12 premiers produits d'une boutique avec les informations essentielles pour une page catalogue :

```graphql
query ProductList($country: CountryCode!) @inContext(country: $country) {
  products(first: 12) {
    edges {
      node {
        id
        title
        handle
        featuredImage {
          url
          altText
          width
          height
        }
        priceRange {
          minVariantPrice { amount currencyCode }
          maxVariantPrice { amount currencyCode }
        }
        variants(first: 3) {
          edges {
            node {
              id
              title
              priceV2 { amount currencyCode }
              availableForSale
            }
          }
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}
```

Le champ `pageInfo` est essentiel pour la **cursor-based pagination**. Utilisez `endCursor` comme point de depart de la requete suivante avec l'argument `after` pour parcourir l'ensemble du catalogue.

#### Interroger une collection et ses produits

```graphql
query CollectionProducts($handle: String!, $first: Int!) {
  collectionByHandle(handle: $handle) {
    title
    description
    products(first: $first, sortKey: BEST_SELLING) {
      edges {
        node {
          id
          title
          handle
          priceRange {
            minVariantPrice { amount currencyCode }
          }
        }
      }
      pageInfo {
        hasNextPage
        endCursor
      }
    }
  }
}
```

Le parametre `sortKey` accepte plusieurs valeurs : `BEST_SELLING`, `CREATED_AT`, `PRICE`, `TITLE`, `RELEVANCE`. Cette flexibilite permet d'adapter le tri selon le contexte de navigation.

#### Construire une page produit detaillee

Pour une page produit complete, combinez les donnees produit, les variantes, les images, les metafields et les recommandations :

```graphql
query ProductDetail($handle: String!, $country: CountryCode!)
  @inContext(country: $country) {
  productByHandle(handle: $handle) {
    id
    title
    descriptionHtml
    vendor
    tags
    seo {
      title
      description
    }
    images(first: 10) {
      edges {
        node {
          url
          altText
          width
          height
        }
      }
    }
    variants(first: 50) {
      edges {
        node {
          id
          title
          priceV2 { amount currencyCode }
          compareAtPriceV2 { amount currencyCode }
          availableForSale
          selectedOptions {
            name
            value
          }
        }
      }
    }
    metafields(identifiers: [
      { namespace: "custom", key: "specifications" },
      { namespace: "custom", key: "care_instructions" }
    ]) {
      key
      value
      type
    }
  }
  productRecommendations(productId: $productId) {
    id
    title
    handle
    priceRange {
      minVariantPrice { amount currencyCode }
    }
    featuredImage {
      url
      altText
    }
  }
}
```

Cette query unique remplace ce qui necessiterait 5 a 7 appels REST distincts.

### Mutations : modifier l'etat du storefront

#### Creer un panier (cart)

La mutation `cartCreate` initialise un nouveau panier :

```graphql
mutation CartCreate($input: CartInput!) {
  cartCreate(input: $input) {
    cart {
      id
      checkoutUrl
      lines(first: 10) {
        edges {
          node {
            id
            quantity
            merchandise {
              ... on ProductVariant {
                id
                title
                priceV2 { amount currencyCode }
              }
            }
          }
        }
      }
      cost {
        totalAmount { amount currencyCode }
        subtotalAmount { amount currencyCode }
      }
    }
    userErrors {
      field
      message
    }
  }
}
```

Variables d'appel :

```json
{
  "input": {
    "lines": [
      {
        "merchandiseId": "gid://shopify/ProductVariant/12345",
        "quantity": 1
      }
    ]
  }
}
```

#### Ajouter et modifier des articles du panier

Pour ajouter des lignes a un panier existant, utilisez `cartLinesAdd` :

```graphql
mutation CartLinesAdd($cartId: ID!, $lines: [CartLineInput!]!) {
  cartLinesAdd(cartId: $cartId, lines: $lines) {
    cart {
      id
      totalQuantity
      cost {
        totalAmount { amount currencyCode }
      }
    }
    userErrors {
      field
      message
    }
  }
}
```

Pour modifier la quantite, utilisez `cartLinesUpdate`. Pour supprimer une ligne, utilisez `cartLinesRemove` avec le `lineId` obtenu lors de la creation.

#### Associer un client au panier

Apres authentification du client, associez son identite au panier via `cartBuyerIdentityUpdate` :

```graphql
mutation CartBuyerIdentityUpdate(
  $cartId: ID!
  $buyerIdentity: CartBuyerIdentityInput!
) {
  cartBuyerIdentityUpdate(cartId: $cartId, buyerIdentity: $buyerIdentity) {
    cart {
      id
      buyerIdentity {
        email
        countryCode
      }
      checkoutUrl
    }
    userErrors {
      field
      message
    }
  }
}
```

Cette association permet d'appliquer les remises personnalisees, de pre-remplir le checkout et de contextualiser les prix selon la localisation du client.

## Patterns avances pour une experience headless riche

### Exploiter les metafields via GraphQL

Les **metafields** etendent le modele de donnees standard de Shopify. Via la Storefront API, vous accedez aux metafields publics definis sur les produits, les variantes, les collections et les clients.

Pour qu'un metafield soit accessible via la Storefront API, il doit etre explicitement active dans les parametres "Storefronts" de la definition du metafield dans l'admin Shopify.

Cas d'usage courants des metafields dans un storefront headless :

- **Fiches techniques** : specifications detaillees, materiaux, dimensions
- **Instructions d'entretien** : guides de lavage, precautions
- **Contenu enrichi** : videos, guides d'utilisation, certifications
- **Donnees SEO** : balises meta personnalisees, donnees structurees supplementaires

### Implementer la tarification internationale

La Storefront API supporte nativement l'**international pricing** via la directive `@inContext`. Cette directive accepte `country` et `language` pour contextualiser l'ensemble de la reponse :

```graphql
query InternationalProduct($handle: String!)
  @inContext(country: FR, language: FR) {
  productByHandle(handle: $handle) {
    title
    variants(first: 5) {
      edges {
        node {
          priceV2 { amount currencyCode }
          compareAtPriceV2 { amount currencyCode }
        }
      }
    }
  }
}
```

Les prix retournes seront automatiquement convertis dans la devise associee au pays specifie, en utilisant les regles de tarification definies dans Shopify Markets. Cette fonctionnalite est disponible sur les boutiques ayant configure Shopify Markets dans leur admin.

### Gestion des comptes clients

La Storefront API offre un ensemble de mutations pour gerer le cycle de vie complet du client :

- `customerCreate` : inscription d'un nouveau client
- `customerAccessTokenCreate` : authentification et generation du delegated access token
- `customerUpdate` : modification du profil (nom, email, telephone)
- `customerAddressCreate` / `customerAddressUpdate` : gestion du carnet d'adresses
- `customer` query : acces a l'historique de commandes, aux adresses et aux metafields client

Le **delegated access token** obtenu via `customerAccessTokenCreate` est valide pour une duree limitee. Implementez un mecanisme de rafraichissement via `customerAccessTokenRenew` pour maintenir les sessions actives sans redemander les identifiants.

### Recherche et filtrage avances

La Storefront API expose une fonctionnalite de recherche predictive via la query `search` et un systeme de filtrage par facettes sur les collections :

```graphql
query SearchProducts($query: String!, $first: Int!) {
  search(query: $query, first: $first, types: [PRODUCT]) {
    edges {
      node {
        ... on Product {
          id
          title
          handle
          priceRange {
            minVariantPrice { amount currencyCode }
          }
        }
      }
    }
    totalCount
  }
}
```

Pour le filtrage par facettes (taille, couleur, prix), utilisez l'argument `filters` sur les queries de collection. Les filtres disponibles sont determines par les metafields et les options de variantes configures dans votre boutique.

## Integration dans un framework moderne

### Architecture avec Next.js App Router

Next.js reste le framework le plus polyvalent pour construire un storefront headless sur Shopify. Avec l'App Router et les React Server Components, les requetes GraphQL vers la Storefront API s'executent directement cote serveur sans exposer les tokens dans le bundle client :

```typescript
// app/products/[handle]/page.tsx
async function getProduct(handle: string) {
  const data = await storefrontQuery(PRODUCT_QUERY, {
    handle,
    country: "FR",
  });
  return data.productByHandle;
}

export default async function ProductPage({
  params,
}: {
  params: { handle: string };
}) {
  const product = await getProduct(params.handle);
  return <ProductTemplate product={product} />;
}
```

Les Server Components eliminent le JavaScript superflu cote client, reduisent le bundle size et ameliorent les Core Web Vitals. Combinez cette approche avec les strategies de rendu **SSR**, **SSG** (via `generateStaticParams`) et **ISR** (via `revalidate`) pour equilibrer fraicheur des donnees et performance.

Pour une comparaison detaillee entre Next.js et Hydrogen, consultez notre [analyse Shopify Hydrogen vs Next.js](/blog/headless/shopify-hydrogen-vs-nextjs).

### Utiliser Hydrogen de Shopify

**Hydrogen** est le framework React officiel de Shopify, base sur Remix. Il fournit des composants et des hooks pre-construits optimises pour la Storefront API :

- `<Money>` : formatage automatique des prix selon la locale
- `<Image>` : chargement optimise des images Shopify avec lazy loading
- `<CartProvider>` : gestion d'etat globale du panier
- `useShopQuery` : hook pour les requetes Storefront API avec cache integre

Hydrogen excelle dans les projets 100% Shopify ou la vitesse de developpement est prioritaire. Il gere nativement le **Server-Side Rendering (SSR)** via Remix et se deploie sur Oxygen, l'infrastructure edge de Shopify.

Le choix entre Next.js et Hydrogen depend de votre ecosysteme : Next.js offre plus de flexibilite pour integrer des sources de donnees multiples (CMS, PIM, search), tandis qu'Hydrogen propose une experience cle en main optimisee pour Shopify.

Pour une vision plus large des frameworks headless e-commerce, consultez notre [guide Next.js e-commerce](/blog/headless/nextjs-ecommerce-guide).

### Strategies de rendu : SSR, SSG et ISR

Le choix de la strategie de rendu impacte directement la performance et la fraicheur des donnees :

- **SSR (Server-Side Rendering)** : la page est generee a chaque requete. Ideal pour les pages panier, les prix dynamiques et le contenu personnalise
- **SSG (Static Site Generation)** : la page est generee au build. Performances maximales pour les pages produit stables et les pages institutionnelles
- **ISR (Incremental Static Regeneration)** : la page est regeneree periodiquement en arriere-plan. Compromis optimal entre performance et fraicheur pour les catalogues de taille moyenne

Pour un catalogue de plus de 10 000 produits, privilegiez l'ISR avec un `revalidate` de 60 a 300 secondes. Cela evite des temps de build excessifs tout en garantissant que les changements de prix ou de stock se refletent en quelques minutes.

## Performance et caching : strategies pour un storefront rapide

### Mise en cache des reponses GraphQL

Contrairement aux API REST ou chaque endpoint dispose d'une URL unique (facilitant le cache HTTP), les requetes GraphQL transitent toutes par un seul endpoint POST. Cela necessite des strategies de cache specifiques :

**Cote serveur (CDN / Edge)** :
- Utilisez des **persisted queries** : transformez les requetes GraphQL en GET avec un hash unique, rendant le cache CDN possible
- Configurez le cache edge (Cloudflare Workers, Vercel Edge) pour mettre en cache les reponses des queries de catalogue avec un TTL de 60 a 300 secondes
- Invalidez selectivement le cache via des webhooks Shopify lors des mises a jour de produits

**Cote client** :
- Apollo Client : cache normalise qui deduplique automatiquement les objets par `id`
- urql : exchanges de cache configurables, du cache document simple au cache normalise via Graphcache
- `stale-while-revalidate` : servez les donnees en cache immediatement tout en rafraichissant en arriere-plan

### Eviter les requetes en cascade (N+1)

Le probleme N+1 survient quand une query initiale declenche N requetes supplementaires pour resoudre les relations. Avec la Storefront API, ce risque apparait principalement dans les Server Components :

```typescript
// A eviter : N+1
const products = await getProducts();
const details = await Promise.all(
  products.map((p) => getProductDetails(p.handle))
);

// Preferable : une seule query avec les champs necessaires
const products = await getProductsWithDetails();
```

Consolidez vos besoins en donnees dans un minimum de queries GraphQL. La Storefront API expose des champs imbriques (variants, images, metafields) precisement pour eviter les allers-retours supplementaires.

### Bonnes pratiques pour des requetes performantes

- **Limitez les champs demandes** : ne demandez que les champs reellement affiches dans l'interface
- **Paginez intelligemment** : utilisez `first: 12` ou `first: 24` selon la taille de votre grille, pas `first: 250`
- **Utilisez des fragments GraphQL** : factorisez les champs communs (ProductCard, PriceDisplay) pour reduire la duplication et simplifier la maintenance
- **Surveillez le query cost** : chaque requete a un cout calcule par Shopify. Les queries complexes avec de nombreuses connexions imbriquees consomment plus de points

## Gestion des rate limits de la Storefront API

La Storefront API utilise un systeme de **rate limits** par IP d'acheteur, fondamentalement different de l'Admin API qui limite par boutique. Ce design permet de gerer des pics de trafic importants sans que les requetes d'un acheteur n'impactent les autres.

Le calcul des couts fonctionne ainsi :

- Chaque requete a un **requested query cost** (cout estime) et un **actual query cost** (cout reel apres execution)
- Le bucket de points se recharge progressivement (restore rate)
- Les reponses incluent un champ `extensions.cost` qui detaille le cout et le solde restant

```json
{
  "extensions": {
    "cost": {
      "requestedQueryCost": 32,
      "actualQueryCost": 24,
      "throttleStatus": {
        "maximumAvailable": 1000,
        "currentlyAvailable": 976,
        "restoreRate": 50
      }
    }
  }
}
```

Strategies pour eviter le throttling :

- Surveillez le champ `currentlyAvailable` et implementez un mecanisme de backoff exponentiel
- Decomposez les queries couteuses en requetes plus legeres reparties dans le temps
- Privilegiez la **cursor-based pagination** avec des lots de taille raisonnable (20-50 items)

## Erreurs courantes et debugging

### Gerer les erreurs GraphQL

Contrairement aux API REST qui utilisent les codes HTTP (404, 500), GraphQL retourne toujours un statut HTTP 200, meme en cas d'erreur applicative. Les erreurs sont encapsulees dans le corps de la reponse :

```json
{
  "data": null,
  "errors": [
    {
      "message": "Field 'nonExistentField' doesn't exist on type 'Product'",
      "locations": [{ "line": 4, "column": 5 }],
      "path": ["productByHandle"]
    }
  ]
}
```

Pour les mutations, verifiez systematiquement le champ `userErrors` en plus du champ `errors` global. Les `userErrors` contiennent les erreurs de validation metier (quantite invalide, variante epuisee).

### Problemes frequents et solutions

**"Field doesn't exist on type"** : cette erreur survient quand vous demandez un champ qui n'existe pas dans la version de l'API utilisee. Verifiez la version dans votre URL (`/api/2026-01/graphql.json`) et consultez le schema via GraphiQL.

**"Access denied"** : verifiez que les permissions Storefront API sont correctement configurees dans le canal Headless. Chaque type de donnees (produits, collections, clients) necessite une permission specifique.

**Metafields vides** : les metafields doivent etre explicitement actives pour l'acces Storefront dans la definition du metafield. Un metafield existant dans l'Admin API peut ne pas etre visible via la Storefront API.

**Pagination incomplete** : n'oubliez pas de verifier `pageInfo.hasNextPage` et d'utiliser `endCursor` pour parcourir l'ensemble des resultats. Sans pagination, la Storefront API retourne un maximum de 250 items par connexion.

## Questions frequentes

### Comment gerer la persistance du panier entre les sessions ?

La Storefront API retourne un `cartId` unique lors de la creation du panier via `cartCreate`. Pour maintenir le panier entre les sessions, stockez ce `cartId` dans un cookie HTTP-only ou dans le localStorage du navigateur. A chaque visite, interrogez le panier existant via la query `cart(id: $cartId)` pour restaurer son contenu.

Pour les clients authentifies, associez le panier a l'identite client via `cartBuyerIdentityUpdate`. Le panier persiste alors cote serveur et se synchronise automatiquement entre les appareils.

### Quelle difference de securite entre public et delegated access token ?

Le **public access token** est concu pour etre expose dans le code front-end. Il donne acces uniquement aux donnees publiques de la boutique (produits, collections, prix) et aux operations de panier. Il ne permet pas d'acceder aux donnees personnelles des clients.

Le **delegated access token** est genere apres authentification du client via `customerAccessTokenCreate`. Il donne acces aux donnees personnelles (adresses, historique de commandes) en plus des donnees publiques. Ce token doit etre gere exclusivement cote serveur pour proteger les informations personnelles.

### La Storefront API est-elle plus rapide qu'un theme Liquid ?

La Storefront API n'est pas inheremment "plus rapide" que Liquid. Liquid est rendu cote serveur par l'infrastructure Shopify, avec des optimisations de cache internes. La difference reside dans le **controle** : avec la Storefront API, vous maitrisez entierement la stack de rendu, le caching et l'optimisation.

Un storefront headless bien optimise (SSR + CDN + cache GraphQL) surpasse generalement un theme Liquid sur les Core Web Vitals, notamment le LCP et l'INP. En revanche, un storefront mal configure peut etre significativement plus lent qu'un theme Liquid standard.

### Dans quels cas est-il deconseille d'utiliser la Storefront API ?

La Storefront API n'est pas adaptee dans les situations suivantes :

- **Boutiques simples sans besoins specifiques** : un theme Liquid standard couvre 80% des besoins avec un cout de developpement bien inferieur
- **Equipes sans competences front-end** : le headless exige une maitrise de React, de la gestion d'etat et du deploiement d'applications
- **Budget limite** : les couts de developpement, d'hebergement et de maintenance d'un storefront headless sont superieurs a ceux d'un theme classique
- **Besoin d'acces complet aux donnees** : la Storefront API est limitee en ecriture. Pour des operations back-office, l'Admin API reste indispensable

## Prochaines etapes pour votre projet headless

La Shopify Storefront API combinee a GraphQL offre un socle technique puissant pour construire des experiences e-commerce sur mesure. Le passage au headless commerce n'est pas une decision purement technique : il engage l'organisation, le budget et les competences de l'equipe sur le long terme.

Pour avancer concretement :

1. **Prototypez** une page produit avec la Storefront API et votre framework de choix (Next.js ou Hydrogen)
2. **Evaluez** les performances par rapport a votre theme actuel sur les Core Web Vitals
3. **Cartographiez** les donnees necessaires (produits, metafields, clients) pour dimensionner votre architecture GraphQL
4. **Planifiez** la strategie de cache et de deploiement avant la mise en production

Pour un accompagnement sur la mise en place de votre architecture headless Shopify, decouvrez notre [service de developpement Shopify headless](/services/builds/shopify-headless).