Un client vendait du thé en vrac et voulait un front en Nuxt pour sa boutique, tout en gardant WooCommerce comme moteur de commande. Le problème est vite apparu : les endpoints REST classiques de WooCommerce (wc/v3/products, wc/v3/orders) exigent des clés API et ne savent rien faire d’un panier anonyme. Impossible de laisser un visiteur ajouter un article sans authentification serveur à serveur.
La réponse s’appelle Store API, un ensemble de routes sous wc/store/v1 pensé dès le départ pour du JavaScript côté client, sans clé consommateur ni secret. Elle alimente les blocs Panier et Commande de WooCommerce, et elle est parfaitement utilisable depuis un front totalement séparé.
Pourquoi ne pas rester sur les endpoints REST classiques
Les routes wc/v3 sont conçues pour l’administration : gestion des produits, des commandes, de la boutique depuis un outil tiers authentifié. Elles ne gèrent pas de notion de panier public. La Store API, elle, expose des routes publiques comme /wc/store/v1/cart, /wc/store/v1/cart/add-item ou /wc/store/v1/checkout, pensées pour un visiteur non connecté.
Elle repose sur deux mécanismes qu’il faut comprendre avant d’écrire la moindre ligne de front : le jeton de panier et le nonce de la Store API.
Récupérer et faire vivre le panier
Une première requête GET vers /wc/store/v1/cart renvoie l’état du panier (vide au départ) accompagné de deux en-têtes de réponse à conserver précieusement :
Cart-Token: un jeton qui identifie le panier anonyme côté serveur, à renvoyer dans les requêtes suivantes.Nonce(transmis viaX-WC-Store-API-Nonce) : obligatoire pour toute requête qui modifie le panier.
Ajouter, modifier et supprimer des articles
Chaque écriture suit le même schéma : on rejoue le Cart-Token reçu et le nonce le plus récent, sinon WooCommerce répond une erreur d’autorisation.
const res = await fetch('/wp-json/wc/store/v1/cart/add-item', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Cart-Token': cartToken,
'Nonce': storeNonce,
},
body: JSON.stringify({ id: 1542, quantity: 2 }),
});
const cart = await res.json();
const newNonce = res.headers.get('Nonce');
Un piège classique : oublier de mettre à jour le nonce après chaque réponse. La Store API en émet un nouveau à chaque appel, et réutiliser l’ancien finit par déclencher des rejets intermittents difficiles à diagnostiquer.
Les routes /cart/update-item et /cart/remove-item suivent exactement la même mécanique, avec l’identifiant de ligne de panier (key) plutôt que l’identifiant produit.
Passer à la caisse
Le tunnel d’achat se termine par un appel unique à /wc/store/v1/checkout, qui accepte les informations de facturation, de livraison et le mode de paiement choisi :
- Récupérer les moyens de paiement disponibles via
/wc/store/v1/checkoutenGET. - Envoyer un
POSTavec adresses etpayment_method. - Rediriger l’acheteur vers l’URL retournée si le moyen de paiement le demande (redirection bancaire).
- Afficher la page de confirmation à partir de la réponse, qui contient déjà le récapitulatif de commande.
Pour les moyens de paiement hébergés (comme une redirection PayPal), la réponse contient un champ payment_result avec l’URL à suivre. Il faut prévoir ce cas dans le front dès la conception, sinon le paiement reste bloqué côté client.
Gérer les erreurs de validation
La Store API renvoie des codes d’erreur explicites : rupture de stock détectée entre l’ajout au panier et le paiement, coupon expiré, adresse incomplète. Chacun arrive avec un code machine du type woocommerce_rest_product_out_of_stock, exploitable directement pour afficher un message ciblé plutôt qu’un message générique.
Sur ce projet, on a fini par stocker le
Cart-Tokendans un cookie plutôt qu’en mémoire vive : ça évite de perdre le panier à chaque rafraîchissement de page, sans dépendre du tout des sessions PHP de WordPress.
Ce qu’on retient
La Store API tient une promesse simple : un panier et un checkout WooCommerce complets, sans jamais toucher aux templates PHP ni imposer une authentification lourde à l’acheteur. Le prix à payer, c’est la discipline sur le couple jeton-nonce, qui doit vivre correctement dans le state du front, cookie ou stockage persistant selon le framework choisi. Une fois ce mécanisme posé, le reste du tunnel d’achat se code comme n’importe quel appel JSON classique.
