API Storefront Shopify: Guide complet pour développeurs et marchands

L'API Storefront Shopify est une API GraphQL publique qui vous permet de créer des expériences d'achat entièrement personnalisées, des storefronts headless et applications mobiles aux intégrations IoT et agents IA, tandis que Shopify gère le backend e-commerce. Contrairement à l'API Admin, elle est conçue pour être appelée de manière sécurisée depuis les navigateurs et clients mobiles. Si vous l'évaluez actuellement, la version stable actuelle est 2026-04 et une version candidate 2026-07 est déjà disponible pour les tests.

Points clés

• L'API Storefront est publique et sûre à appeler côté client ; l'API Admin doit rester sur un serveur sécurisé.
• Les mutations panier (cartCreate, cartLinesAdd, cartBuyerIdentityUpdate) sont les opérations d'écriture essentielles que chaque build nécessite.
• Les versions d'API suivent un calendrier trimestriel : 2026-01, 2026-04, 2026-07, 2026-10. L'ancienne version 2024-10 arrive en fin de vie en octobre 2026.
• Hydrogen 2026.4.0 a rendu le proxy API Storefront obligatoire et activé le consentement backend par défaut, deux changements majeurs qui nécessitent un audit avant la mise à jour.
• Depuis Hydrogen 2026.1.4, chaque storefront Hydrogen sur Oxygen expose automatiquement un point d'accès MCP à /api/mcp, le transformant en endpoint e-commerce compatible avec les agents IA sans code personnalisé.

Qu'est-ce que l'API Storefront Shopify ?

L'API Storefront est l'API GraphQL orientée client de Shopify. Elle donne aux développeurs un accès en lecture aux produits, collections, métaobjets et menus, plus un accès en écriture pour les deux choses que les acheteurs font réellement : gérer un panier et s'authentifier en tant que client.

Voici comment la propre documentation de Shopify encadre son modèle d'accès : l'API Storefront est principalement en lecture seule, à l'exception de l'authentification et de la gestion du panier. Cette limite est intentionnelle. Vous pouvez récupérer tous les détails produits, créer une interface de filtre en direct et construire un flux de paiement complet sans jamais toucher à une donnée d'identification secrète.

Le motif d'endpoint est simple :

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

Chaque requête a besoin d'un en-tête Shopify-Storefront-Public-Token (ou l'équivalent du jeton privé pour les appels Hydrogen côté serveur). Le jeton n'est pas secret et peut être intégré au code du navigateur ou mobile. Votre clé d'API Admin et le mot de passe, en revanche, ne doivent jamais apparaître dans le code côté client.

API Storefront vs API Admin : la vraie différence

C'est la question que chaque marchand et développeur pose en premier, et la réponse est architecturale, pas simplement une liste de fonctionnalités.

L'API Admin vous donne un accès complet en lecture et écriture aux données de votre boutique Shopify : commandes, clients, produits, inventaire, expédition, analyse et bien plus. L'API Storefront intentionnellement n'a pas ces fonctions administratives. Vous ne pouvez pas modifier les commandes, gérer l'inventaire ni accéder à l'analyse interne via elle. Ce n'est pas une limitation à contourner ; c'est la limite de sécurité qui vous permet d'intégrer le jeton de manière sécurisée dans un composant React.

Une erreur courante : utiliser les identifiants de l'API Admin dans le code côté client. Cela expose vos identifiants de boutique au public. Gardez toujours les appels de l'API Admin sur un serveur backend sécurisé. Si vous avez besoin d'un accès côté client aux données de la boutique, c'est exactement pour cela que l'API Storefront a été créée.

Capacités essentielles : ce que vous pouvez vraiment créer

Requêtes produits et collections

Récupérez les titres de produits, descriptions, tarification des variantes, statut d'inventaire, images et métachamps. Comme GraphQL vous permet de ne demander que les champs dont vous avez besoin, une requête de carte produit peut retourner une réponse compacte de 3 champs au lieu d'une charge utile REST volumineuse. La vitesse et l'efficacité d'obtenir seulement les données que vous demandez la rend idéale pour les applications sensibles aux performances.

Un changement récent important : les variantes de produit GraphQL supportent désormais jusqu'à 2 000 par produit, augmentées par rapport au plafond précédent de 100 variantes. Si vous vendez des produits configurables (taille x couleur x matériau), cela compte.

Mutations panier

L'objet Panier est le cœur de chaque build API Storefront. La surface de mutation actuelle comprend :

• cartCreate, créer un nouveau panier et ajouter optionnellement un article en une seule requête
• cartLinesAdd, ajouter une ou plusieurs variantes de produit à un panier existant
• cartLinesUpdate, mettre à jour la quantité sur les lignes existantes (accepte jusqu'à 250 valeurs par appel)
• cartLinesRemove, supprimer les lignes par ID
• cartDiscountCodesUpdate, appliquer ou effacer les codes de réduction (remplace tous les codes existants par la liste fournie)
• cartGiftCardCodesAdd / cartGiftCardCodesRemove, gérer le remboursement des cartes cadeaux
• cartBuyerIdentityUpdate, associer un client connecté, définir un emplacement d'entreprise B2B ou configurer les préférences de paiement comme la méthode de livraison
• cartMetafieldsSet, écrire des métachamps arbitraires sur le panier pour la logique de paiement personnalisée

Un ajout récent utile à connaître : le type CartLine retourne maintenant un champ viewKey, ce qui vous permet de corréler les lignes retournées avec le view_key envoyé à cartLinesUpdate et cartLinesRemove. Utile quand vous créez des mises à jour d'interface utilisateur optimistes.

Consentement conforme à la vie privée

Depuis la version 2025-10 de l'API Storefront et au-delà, la directive @inContext accepte un argument visitorConsent. Cela vous permet d'encoder l'état du consentement directement dans l'appel de création de panier et de l'inclure automatiquement dans le checkoutUrl résultant. Résultat : les flux de conformité RGPD et CCPA sans couche d'écriture de cookie séparée.

Métaobjets et accès fermé par jeton

Certaines fonctionnalités nécessitent une authentification basée sur jeton au-delà du jeton d'accès public. Les étiquettes de produit, métaobjets, métachamps, menus de navigation de magasin et données client se situent tous derrière un accès limité au jeton. Demander ces étendues se fait quand vous créez l'application API Storefront dans l'admin Shopify.

Versioning d'API : ce que les marchands et développeurs doivent suivre

L'API Storefront de Shopify suit un calendrier de publication trimestriel : les versions s'appellent 2026-01, 2026-04, 2026-07 et 2026-10. Chaque version est prise en charge pendant 12 mois après sa publication. Les appels aux versions d'API non supportées entraîneront la suppression ou le blocage de l'installation des applications.

Les dates clés en ce moment sont :

• 2026-04 est la version stable actuelle (la plus récente).
• 2026-07 est la version candidate, liée à l'édition d'été 2026 de Shopify (nom de code Compass), qui contient 65 mises à jour de produits dont des changements majeurs aux structures de requête panier et produit.
• 2024-10 arrive en fin de vie en octobre 2026. Si votre build headless est toujours sur cette version, vous avez un délai fini pour la migration.

Les changements majeurs de 2026-07 affectent chaque build headless, Hydrogen, Next.js Commerce, Nuxt ou entièrement personnalisé. Shopify fournit des codemods pour les projets Hydrogen afin d'automatiser les migrations de requêtes.

Pour les marchands évaluant s'il faut agir maintenant : si vous exécutez un build headless personnalisé sur une version plus ancienne que 2025-04, planifiez un audit de version avec votre développeur ce trimestre. Voir notre page de services de développeur Shopify pour ce qu'un audit de version implique généralement.

La connexion Hydrogen : le proxy API Storefront est maintenant obligatoire

Hydrogen est le framework basé sur React de Shopify construit directement au-dessus de l'API Storefront, et en 2026, la relation entre les deux s'est considérablement resserrée.

Hydrogen 2026.4.0 (publié le 17 avril 2026) a introduit deux changements majeurs :

1. Le proxy API Storefront est maintenant toujours activé. L'option de configuration proxyStandardRoutes a été supprimée. Si un gestionnaire de requête s'exécute sans instance storefront dans son contexte de chargement, il lève une erreur d'exécution. Tout setup Hydrogen personnalisé qui contournait le proxy doit être mis à jour.
2. Le mode consentement backend est maintenant le défaut. Hydrogen ne s'appuie plus sur le cookie _tracking_consent côté client. Le consentement est maintenant géré via des cookies définis par le serveur écrits via le proxy API Storefront. Les bannières de consentement personnalisées qui lisent document.cookie pour _tracking_consent verront une valeur vide après la mise à jour.

La raison pour laquelle ces deux changements sont couplés : le but entier du mode consentement backend est que les écritures de consentement ne peuvent pas échouer silencieusement quand un proxy manque. Le proxy devenant obligatoire était le préalable.

Si vous exécutez un setup Hydrogen personnalisé (tout projet qui n'est pas un squelette create-hydrogen propre), auditez vos appels createRequestHandler et logique de bannière de consentement avant de mettre à jour vers 2026.4.x.

Le plus grand changement en 2026 : votre storefront est maintenant un point d'accès agent IA

C'est le développement qui change le rôle de l'API Storefront le plus fondamentalement.

Hydrogen 2026.1.4 a ajouté un support proxy MCP (Model Context Protocol) Storefront intégré. Chaque boutique Hydrogen sur Oxygen expose maintenant un point d'accès MCP à /api/mcp sans configuration personnalisée. Ce que cela signifie en pratique : les assistants IA comme ChatGPT, Perplexity et les agents d'achat personnalisés peuvent découvrir vos produits, gérer les paniers et guider les acheteurs via le paiement en utilisant le langage naturel, tout alimenté par des données en temps réel de l'API Storefront.

Shopify expose trois surfaces MCP distinctes :

• MCP Catalogue, découverte de produits mondiale parmi les marchands Shopify
• MCP Storefront, recherche spécifique au marchand, politiques et FAQ
• MCP Paiement, création de panier programmatique, mises à jour et finalisation du paiement

La découverte publique de produits via MCP Storefront ne nécessite pas d'authentification supplémentaire. Les opérations panier authentifiées utilisent l'en-tête Shopify-Storefront-Private-Token existant que votre application Hydrogen envoie déjà.

Pour vérifier que le proxy est actif sur votre boutique : allez à /api/mcp sur votre déploiement Oxygen. S'il est transféré au serveur MCP Storefront de Shopify, vous êtes en direct.

Pour les marchands pas encore sur Hydrogen, c'est une raison concrète d'évaluer la migration. Les thèmes Liquid sur le CDN de Shopify offrent des performances cohérentes mais fixes. Hydrogen sur Oxygen offre cette ligne de base de performance plus l'intégration d'agent IA sans dégradation. Le calcul du ROI pour les fonctionnalités d'e-commerce IA basculait en faveur d'Hydrogen. Vous pouvez explorer ce que la migration Hydrogen implique sur notre page de développeur headless Shopify.

Liste de contrôle pratique pour les marchands et développeurs

Si vous exécutez un storefront Hydrogen :

• Confirmez que vous êtes sur l'API Storefront 2026-04 (la plus récente actuelle)
• Auditez createRequestHandler pour l'option proxyStandardRoutes maintenant supprimée
• Vérifiez que votre banneau de consentement lit les cookies définis par le serveur, pas _tracking_consent
• Testez /api/mcp sur votre déploiement Oxygen pour confirmer que MCP est actif
• Commencez à tester contre la version candidate 2026-07 maintenant ; n'attendez pas octobre

Si vous exécutez un build headless personnalisé (Next.js, Nuxt, etc.) :

• Identifiez votre version d'API actuelle et mappez-la contre l'extinction en octobre 2026 de 2024-10
• Examinez le changelog 2026-07 pour les changements majeurs aux structures de requête panier et produit
• Planifiez les codemods ou les mises à jour de requête manuelles avant le prochain cycle Shopify Editions

Si vous exécutez un thème Liquid standard :

• L'API Storefront est toujours pertinente si vous utilisez une application tierce qui l'appelle côté client
• Vérifiez que ces applications ciblent 2026-04 ou une version plus récente
• Considérez si les capacités d'agent IA dans Hydrogen justifient une évaluation de migration

L'API Storefront n'est plus seulement l'API « Shopify headless ». C'est la couche de données qui connecte votre catalogue à chaque surface qu'un acheteur peut utiliser, navigateur, mobile, voix et maintenant agents IA. Garder votre version à jour et votre setup Hydrogen aligné avec les exigences de proxy et de consentement de Shopify est le travail de maintenance qui maintient ces surfaces ouvertes.