Shopify headless avec Next.js : collections, produits, panier et commandes via l’API

Les thèmes Shopify conviennent à la grande majorité des boutiques. Mais certaines marques se heurtent à leurs limites : un design très spécifique, des performances à pousser au maximum, une boutique qui doit cohabiter avec un site de contenu, un configurateur ou un espace client sur-mesure. La solution s’appelle Shopify headless : on garde Shopify pour tout ce qu’il fait très bien, et on construit la vitrine avec un framework moderne comme Next.js. Voici comment ça fonctionne, concrètement.

Headless, c’est quoi ?

Une boutique Shopify classique, c’est un back-office (produits, stocks, commandes, clients) et une « tête » : le thème qui affiche la boutique. En headless, on retire cette tête. Shopify devient un moteur e-commerce accessible par API, et le site visible par les clients est une application indépendante, développée sur-mesure et hébergée séparément.

• Shopify gère : le catalogue, les variantes, les stocks, les prix et devises, les promotions, le paiement, les commandes, les expéditions, le back-office.
• Next.js gère : l’affichage des pages, la navigation, le design, le contenu éditorial, les performances et le référencement.
• L’API fait le lien : la Storefront API de Shopify, en GraphQL, fournit les données produits et gère le panier.

L’architecture type

1. Next.js génère les pages collections et produits en statique, à partir des données de la Storefront API.
2. Un CMS (par exemple Payload, Sanity ou les métachamps Shopify) gère les contenus éditoriaux : page d’accueil, lookbooks, blog. Voir notre article sur les CMS headless.
3. Le panier est créé et mis à jour via la Cart API de Shopify, depuis le navigateur ou depuis le serveur.
4. Le paiement se fait sur le checkout Shopify, sécurisé et optimisé, ou via une commande créée par l’Admin API dans certains cas.
5. Des webhooks Shopify préviennent le site quand un produit, un prix ou un stock change, pour régénérer uniquement les pages concernées.

Afficher les collections et les produits

La Storefront API s’interroge en GraphQL avec un jeton d’accès public, créé depuis le canal « Headless » de Shopify. On demande exactement les champs dont on a besoin, rien de plus. Exemple pour une page collection :

query Collection($handle: String!) {
  collection(handle: $handle) {
    title
    description
    seo { title description }
    products(first: 24) {
      nodes {
        handle
        title
        featuredImage { url altText width height }
        priceRange {
          minVariantPrice { amount currencyCode }
        }
      }
    }
  }
}

Côté Next.js, l’appel se fait depuis un composant serveur. Les données sont mises en cache et associées à une étiquette, ce qui permet de régénérer les pages à la demande quand Shopify signale une modification :

export async function shopifyFetch(query, variables, tags = []) {
  const res = await fetch(process.env.SHOPIFY_STOREFRONT_URL, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Shopify-Storefront-Access-Token': process.env.SHOPIFY_STOREFRONT_TOKEN,
    },
    body: JSON.stringify({ query, variables }),
    next: { tags },
  });

  const { data, errors } = await res.json();
  if (errors) throw new Error(errors[0].message);
  return data;
}

Les pages produits suivent le même principe : titre, description, images, variantes (taille, couleur) avec leur disponibilité, métachamps pour les informations complémentaires (composition, guide des tailles, conseils d’entretien). Le filtrage et le tri des collections sont aussi disponibles dans l’API.

Gérer le panier

Le panier est géré par Shopify, pas par votre site : c’est ce qui garantit des prix, des promotions et des stocks toujours justes. On crée un panier au premier ajout, on conserve son identifiant dans un cookie, puis on y ajoute, modifie ou supprime des lignes.

mutation CreateCart($lines: [CartLineInput!]!) {
  cartCreate(input: { lines: $lines }) {
    cart {
      id
      checkoutUrl
      totalQuantity
      cost {
        totalAmount { amount currencyCode }
      }
    }
    userErrors { field message }
  }
}

Les mutations cartLinesAdd, cartLinesUpdate et cartLinesRemove gèrent la suite. Les codes promo, les notes de commande et les attributs personnalisés (gravure, message cadeau) passent aussi par le panier. Avec les Server Actions de Next.js, ces appels restent côté serveur et le jeton n’est jamais exposé inutilement.

Créer la commande

La voie standard : le checkout Shopify

Chaque panier possède une adresse checkoutUrl. Au moment de payer, le client est redirigé vers le checkout Shopify, qui gère adresses, frais de port, taxes, paiement (Shop Pay, Apple Pay, cartes), détection de la fraude et création de la commande. C’est la solution que nous recommandons dans la plupart des cas : le checkout Shopify est l’un des plus performants du marché, et vous n’avez pas à gérer de données bancaires. Il se personnalise aux couleurs de votre marque.

La création de commande par l’Admin API

Dans certains cas, la commande doit être créée directement par l’API, côté serveur, avec l’Admin API de Shopify :

• Commandes professionnelles : un revendeur passe commande sur son portail, et la commande est créée avec ses conditions (tarifs dédiés, paiement à 30 jours) via une commande brouillon puis finalisée. Voir notre article sur le portail B2B Shopify.
• Paiement géré ailleurs : marketplace, devis signé, paiement sur facture ou par un prestataire externe. La commande est alors enregistrée dans Shopify pour centraliser stocks, expéditions et comptabilité.
• Devis : une commande brouillon est préparée par votre équipe, puis envoyée au client avec un lien de paiement.

Comptes clients, marchés et langues

La Customer Account API permet d’afficher l’historique de commandes et les adresses du client dans votre propre interface. Shopify Markets reste utilisable : la directive @inContext de la Storefront API renvoie les prix dans la devise et la langue du pays visé. Pour le référencement international, les balises hreflang sont à générer côté Next.js, comme expliqué dans notre article sur les sites multilingues.

Le SEO : un avantage, et une responsabilité

Une boutique headless bien faite est extrêmement rapide : pages statiques servies depuis un CDN, images optimisées, quasiment pas de JavaScript inutile, pas d’applications qui injectent leurs scripts partout. C’est un atout majeur pour les Core Web Vitals et pour la conversion. Mais tout ce que le thème Shopify faisait automatiquement devient votre responsabilité :

• le rendu des pages produits côté serveur ou en statique (voir SSR, SSG ou CSR) ;
• le sitemap, les balises canoniques et les balises title et description ;
• les données structurées Product, avec prix et disponibilité ;
• les redirections, notamment si vous migrez depuis un thème Shopify existant ;
• la gestion des produits en rupture ou supprimés.

Avantages et limites

Les avantages

• Une liberté totale de design et d’expérience, sans les contraintes du thème.
• Des performances de premier ordre, même avec un catalogue important.
• Un seul site pour le contenu et la boutique, avec une seule identité.
• La possibilité de connecter d’autres sources : CMS, configurateur, PIM, ERP, CRM.

Les limites

• Un coût de développement nettement plus élevé qu’un thème.
• Une partie des applications Shopify ne fonctionne pas sans thème (widgets d’avis, upsells, programmes de fidélité) : il faut passer par leur API ou les remplacer.
• Une maintenance technique à prévoir, comme pour tout site sur-mesure. Voir notre article sur la maintenance d’un site.
• Votre équipe garde le back-office Shopify, mais ne peut plus modifier la mise en page avec l’éditeur de thème : c’est le CMS qui prend le relais.

Next.js ou Hydrogen ?

Shopify propose son propre framework headless, Hydrogen, avec un hébergement intégré, Oxygen. C’est une excellente option si la boutique est le cœur du projet. Next.js est plus pertinent quand le site mêle beaucoup de contenu, d’autres sources de données ou des fonctionnalités métier, et quand votre équipe ou votre agence travaille déjà avec. Dans les deux cas, la Storefront API est la même.

Pour qui ?

Le headless n’est pas pour une boutique qui démarre : un bon thème Shopify bien optimisé reste plus rentable, comme nous l’expliquons dans notre guide pour créer une boutique Shopify. Il devient intéressant pour les marques établies qui veulent une expérience distinctive, les boutiques dont la performance est un enjeu fort, et les projets qui combinent e-commerce, contenu et outils métier.

C’est exactement le type de projet que nous aimons. Notre agence Shopify à Marseille développe des boutiques headless en Next.js, et nos intégrations API connectent Shopify à vos autres outils. Parlons de votre projet : nous vous dirons franchement si le headless est le bon choix pour vous.