#Le panier
Sur une boutique, le panier appartient au thème, comme chez Shopify. La
plateforme fournit les données du panier, son API et la page de paiement ; le
thème décide s’il y a un tiroir, une page /cart, les deux ou rien, comment ils
se présentent, et quels réglages le marchand voit dans l’éditeur. Aucun réglage
de panier n’est ajouté par la plateforme : ceux qui existent sont déclarés par
le thème, dans le {% schema %} de ses sections.
La page de paiement (/checkout) reste un document de la plateforme : aucun
gabarit, aucune feuille, aucun script du thème n’y entre.
#Ce que fournit la plateforme
cartobjetLe panier, aux noms de Shopify : cart.items, cart.item_count,
cart.total_price, cart.items_subtotal_price, cart.original_total_price,
cart.total_discount, cart.cart_level_discount_applications, cart.note,
cart.attributes, cart.currency.iso_code, cart.empty, cart.token. Les
montants sont en centimes, à passer dans | money. Présent sur toute page
d’une boutique. Ce que la visiteuse a écrit — cart.note, les valeurs de
cart.attributes et des properties d’une ligne — arrive déjà échappé : à
poser tel quel, sans | escape.
routesobjetLes adresses, préfixées comme le site : routes.cart_url,
routes.cart_add_url, routes.cart_change_url, routes.cart_update_url,
routes.cart_clear_url, routes.root_url, routes.search_url,
routes.collections_url, routes.all_products_collection_url,
routes.account_url (vide sans comptes clients).
moneyfiltreDes centimes en prix lisible, dans la devise du panier :
{{ cart.total_price | money }} → 24,90 €.
boutique.en_pausebooléenVrai quand le site est en pause : les produits restent visibles, mais la
boutique ne prend plus de commande. Absent sinon, donc
{% if boutique.en_pause %} suffit. Le thème met alors « Boutique en pause » à
la place de son bouton d’ajout au panier (et retire une barre d’achat collée,
s’il en a une). Le reste est tenu par la plateforme : l’ajout (/cart/add)
répond 422 avec la phrase à afficher (description), le composant du panier
remplace son bouton de commande par « Boutique en pause », et le paiement est
refusé.
{%- if boutique.en_pause -%}
<button type="button" class="ajouter" disabled>Boutique en pause</button>
{%- else -%}
<button type="submit" class="ajouter">Ajouter au panier</button>
{%- endif -%}Une ligne de cart.items porte key, id (la variante, ou le produit quand il
n’en a pas), quantity, title, product_title, variant_title, url,
image, properties (la personnalisation : { "Prénom": "Léa" }),
options_with_values, price, final_price, final_line_price,
original_line_price, total_discount, et deux champs de plus que Shopify :
offerte (un article ajouté par une offre de la boutique, qui ne se change pas)
et stock_insuffisant.
Sur une page servie à toutes, cart est le panier vide. Les pages d’un site
sont gardées en cache et servies telles quelles à chaque visiteuse : leur HTML ne
peut pas dépendre de la sienne. cart est celui de la visiteuse sur /cart
quand elle a un panier (la page est alors rendue pour elle), et dans les sections
que l’API rend à la demande. Ailleurs, un compteur se remplit dans la page :
[data-wc-panier-compte], l’évènement wcp:maj, ou /cart.js.
#Trois façons d’avoir un panier
#1. Le composant de la plateforme, réglé par le thème
C’est ce que font les thèmes de Webcosa. Une section de la coquille déclare les
réglages du panier dans son schéma et en pose les valeurs dans la page ; le
composant du panier de la plateforme les lit et dessine le tiroir et la page
/cart aux couleurs du thème. Le nom de la section est libre ; celui des
thèmes de Webcosa est cart-drawer.
<script type="application/json" data-wc-panier>{{ section.settings | json }}</script>
{% schema %}
{
"name": "Panier",
"settings": [
{ "type": "select", "id": "forme", "label": "Forme du panier", "default": "tiroir",
"options": [{ "value": "tiroir", "label": "Tiroir" }, { "value": "page", "label": "Page /cart" }] },
{ "type": "checkbox", "id": "ouvrir_a_l_ajout", "label": "Ouvrir le panier à chaque ajout", "default": true },
{ "type": "text", "id": "titre", "label": "Titre du panier", "default": "Votre panier" },
{ "type": "text", "id": "bouton", "label": "Bouton du panier", "default": "Paiement sécurisé" }
]
}
{% endschema %} {% section 'pied' %}
{% section 'cart-drawer' %}
</body>Le composant comprend ces identifiants de réglage ; un thème n’en déclare que
ceux qu’il veut, les autres gardent la valeur de la plateforme. Une valeur
illisible (un choix inconnu, un texte trop long ou qui contient <) est
ignorée.
| Identifiant | Type | Ce qu’il règle |
|---|---|---|
forme | tiroir ou page | un tiroir sur le côté, ou la page /cart |
ouvrir_a_l_ajout | booléen | le panier s’ouvre à chaque ajout |
vignettes | booléen | les photos des lignes |
code_reduction | booléen | la ligne « Ajouter un code de réduction » |
livraison_estimee | booléen | le port du mode le moins cher dans le total |
livraison_offerte | booléen | la carte « Plus que 21 € pour la livraison offerte », lue dans les modes de livraison |
cadenas | booléen | un cadenas dans le bouton |
logos_paiement | booléen | les logos des moyens que la caisse propose vraiment |
icone_sous_bouton | aucune, retour, cadenas, camion, bouclier | l’icône de la ligne sous le bouton |
recommandations | booléen | des produits associés à ceux du panier |
recommandations_source | associes, collection, les_deux | d’où ils viennent |
recommandations_nombre | 1 à 6 | combien |
titre | texte (60) | le titre du panier |
texte_vide | texte (160) | le panier vide |
bouton | texte (40) | le bouton qui mène au paiement |
sous_bouton | texte (160), facultatif | une ligne sous le bouton |
texte_livraison_restant | texte (120) avec {montant} | la carte de livraison offerte, en chemin |
texte_livraison_atteinte | texte (120) | la carte, seuil atteint |
titre_recommandations | texte (60) | le titre des recommandations |
Le composant se règle aussi par CSS : il pose ses éléments sous .wcp, le
bouton principal est .wcp-commander, les boutons secondaires .wcp-second. Le
contenu d’un <template data-wc-panier-note> posé dans la page est recopié sous
la carte de livraison offerte à chaque rendu (une ligne de saison).
La page /cart du thème pose l’emplacement que le composant remplit :
{
"sections": { "panier": { "type": "main-cart", "settings": {} } },
"order": ["panier"]
}<h1 class="masque">{{ page.titre | escape }}</h1>
<div id="wc-panier-page"></div>
{% schema %}{ "name": "Page du panier", "settings": [] }{% endschema %}#2. Votre propre panier, sur l’API
Un thème importé de Shopify garde son tiroir et sa page : templates/cart.json
et ses sections lisent cart, ses formulaires postent vers
routes.cart_add_url, son script appelle l’API ci-dessous. Il ne pose pas
data-wc-panier, et le composant de la plateforme ne dessine rien.
Les scripts en ligne d’une section sont admis ; assets/ n’accepte ni .js ni
autre chose que du CSS et du SVG.
#3. Pas de panier
Un thème sans section qui pose data-wc-panier n’a pas de tiroir : les liens
vers /cart y mènent, et l’ajout depuis une fiche aussi (la forme « page » de
Shopify). Sans templates/cart.json, /cart montre le panier minimal de la
plateforme dans la coquille du thème, et le paiement reste à un clic. L’éditeur
d’une boutique le dit : « Ce thème n’a pas de panier ».
#L’API
Sur l’adresse de la boutique, aux chemins et aux formes de Shopify. Les réponses sont du JSON, jamais en cache.
| Demande | Corps | Réponse |
|---|---|---|
GET /cart.js (ou .json) | — | le panier |
POST /cart/add.js | { "items": [{ "id", "quantity", "properties" }] }, ou un article à plat | les lignes ajoutées ({ items }), ou la ligne seule pour un article à plat |
POST /cart/change.js | { "line": 1, "quantity": 0 } ou { "id": "<key>", "quantity": 2, "properties": {…} } | le panier |
POST /cart/update.js | { "updates": { "<key>": 2 }, "note": "…", "attributes": { "cadeau": "oui" }, "discount": "NOEL10" } | le panier |
POST /cart/clear.js | — | le panier, vide (la note et les attributs restent) |
POST /cart/add, /cart/change, /cart/update, /cart/clear | un formulaire | 303 vers /cart (/checkout si le formulaire porte checkout) |
GET /cart/change?line=1&quantity=0 | — | 303 vers /cart (une quantité seulement : des properties dans l’adresse sont refusées, 405) |
id est l’identifiant d’une variante, ou d’un produit sans variante. Les
properties sont rapprochées des champs de personnalisation du produit, par
leur identifiant ou leur libellé (« Prénom ») ; une clé qui commence par _ est
un champ discret. Une propriété qui ne correspond à aucun champ n’est pas
gardée.
const r = await fetch("{{ routes.cart_add_url }}.js", {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({ items: [{ id, quantity: 1, properties: { Prénom: "Léa" } }], sections: "mon-tiroir" }),
});
const reponse = await r.json();
if (!r.ok) return afficher(reponse.description);
tiroir.innerHTML = reponse.sections["mon-tiroir"];
window.dispatchEvent(new CustomEvent("wcp:relire"));sections (une liste, ou une chaîne séparée par des virgules, cinq au plus)
renvoie, dans sections, le HTML de ces sections du thème publié rendues avec
le nouveau panier — la « Section Rendering API » de Shopify. Une section de la
coquille prend ses réglages enregistrés ; une section du gabarit cart, les
siens. Une section absente ou en erreur vaut null.
Les erreurs ont la forme de Shopify : { "status": 422, "message": "Cart Error", "description": "…" }. 422 : article inconnu, hors vente, stock
insuffisant, personnalisation incomplète, panier plein ; 400 : ligne
introuvable ; 403 : demande venue d’un autre site ; 429 : trop de demandes.
#Les évènements
| Évènement | Sur | Sens |
|---|---|---|
wcp:maj | window | le panier a changé ; detail.item_count |
wcp:rendu | window | le composant vient de se redessiner |
wcp:ouvrir | window | à envoyer : ouvrez le tiroir du composant |
wcp:relire | window | à envoyer après vos appels à l’API : le composant relit le panier |
cart:update | document | celui des thèmes Horizon, compris comme wcp:relire |
Les compteurs [data-wc-panier-compte] et les liens a[href="/cart"] (ou
[data-wc-panier-ouvrir]) sont tenus par le composant sur toute page.
#Ce qui est garanti
- Aucun prix n’est cru. Le panier ne retient que des identifiants, des
quantités, des saisies et un code. Prix, stock, remises et port sont relus
dans le catalogue à chaque réponse, par la même fonction que le paiement ; un
priceenvoyé est ignoré. La caisse recalcule tout encore une fois. - Le panier vit dans un cookie de l’hôte de la boutique,
__Host-cart_<boutique>(cart_<boutique>en http, sur un poste de développement) : aucun autre hôte ne peut le poser,SameSite=Lax,Secure, trente jours. Il ne contient rien de secret ; il tient une quarantaine de lignes simples, au-delà l’ajout est refusé. - Le recalcul est limité à 300 demandes par dix minutes, par connexion et par boutique.
- Une écriture venue d’un autre site est refusée (
Origind’un autre hôte). - Le paiement est un document de la plateforme. Le bouton du panier mène à
/checkout; rien du thème n’y entre.

