Combora — Manuel d'utilisation

1Ce qu'est Combora

Combora crée des bundles et des offres automatiques dans votre boutique Shopify : elle regroupe des produits, applique la bonne remise dans le panier et au paiement, et affiche l'offre dans votre thème grâce à des blocs prêts à l'emploi. Vous configurez l'offre dans l'admin, et la remise est calculée par une Function Shopify à l'intérieur même du paiement — le prix facturé est celui que calcule la plateforme elle-même, et non un script dans le navigateur.

Il existe 8 types de bundle. Ce tableau vous aide à choisir :

Si vous hésitez entre les types, l'application dispose de son propre guide : sous Créer un bundle, le lien « Pas sûr lequel choisir ? » ouvre un assistant, et chaque type possède un panneau « Voir comment ça marche » avec des exemples.

2Prise en main

2.1 Ce que l'application crée à l'installation

Installer Combora ne change rien de visible dans votre boutique. En arrière-plan, l'application prépare les structures de données où elle publiera vos bundles (des metaobjects et des metafields préfixés par combora — le détail technique se trouve dans l'annexe pour développeurs) ainsi qu'une seule remise automatique nommée « Combora » sous Remises, qui est celle qui applique tous les prix. Ne la supprimez pas et ne la modifiez pas à la main : l'application la maintient elle-même.

2.2 Activer le moteur de cadeau (app embed)

Si vous allez utiliser Cadeau pour tout achat (ou des combos avec un cadeau), activez l'intégration d'application Combora Gift : Boutique en ligne → Personnaliser → Paramètres du thème → Intégrations d'application → Combora Gift. C'est le composant qui ajoute et retire le cadeau du panier automatiquement. Sans lui, la remise du cadeau resterait correcte, mais le produit cadeau ne s'ajouterait pas de lui-même.

2.3 Ajouter les blocs à votre thème

Chaque type de bundle s'affiche sur la boutique via un bloc de thème. Vous les ajoutez une seule fois sous Boutique en ligne → Personnaliser, dans le modèle correspondant :

Vous n'avez pas besoin de mémoriser tout cela : chaque éditeur de bundle possède une carte « Où cela s'affiche » qui nomme le bon bloc, ainsi qu'un lien « Aperçu sur votre thème en ligne » qui ouvre l'éditeur de thème avec ce bloc déjà prêt à être inséré dans le bon modèle.

3Tour de l'application

L'application se trouve sous Applications → Combora. Le menu compte six entrées — Accueil, Bundles, Statistiques, Forfaits, Aide et Paramètres — plus le chat d'assistance, présent sur chaque écran :

Accueil

L'écran de bienvenue et le pouls de votre installation. Tant que la configuration n'est pas terminée, il affiche une checklist en trois étapes — créer votre premier bundle, le publier et (si votre offre est un cadeau pour tout achat) activer le moteur de cadeau dans votre thème. La checklist n'est pas décorative : chaque étape ne se coche que si elle s'est réellement produite dans votre boutique, le bouton d'action n'apparaît que sur l'étape en attente, et si vous dépubliez tout par la suite, la checklist revient refléter la réalité. Une fois terminée, Accueil célèbre l'événement avec un lien direct pour voir votre boutique (vous pouvez masquer la note quand vous le souhaitez).

Sous la checklist : vos bundles les plus récents avec leur statut, une bande d'attention si un bundle a besoin d'être révisé (par exemple parce que vous avez archivé un produit qui le composait — l'application le détecte elle-même et le signale sans rien dépublier), et une bande avec votre forfait actuel.

Bundles

La liste de tous vos bundles : recherche par nom, filtre par statut (Publié / Brouillon), actions par ligne (dupliquer, publier/mettre en brouillon, supprimer) et sélection multiple avec actions groupées. Tout se crée depuis ici avec Créer un bundle.

Statistiques

Les indicateurs de performance de vos bundles sur des commandes réelles : revenu attribué, % de commandes avec un bundle, économies accordées, valeur moyenne de commande et un graphique dans le temps. Détail à la section 17.

Forfaits

Votre forfait actuel et les options de mise à niveau. Le forfait Gratuit autorise 3 bundles publiés à la fois ; les forfaits payants n'ont pas de limite (section 18).

Aide

Questions fréquentes et explications des concepts (arbitrage entre bundles, cadeaux, blocs).

Diagnostic (un onglet à l'intérieur d'Aide)

Le panneau de santé et d'assistance vit comme un onglet à l'intérieur d'Aide (sélecteur « Guides | Diagnostic » en haut) : des vérifications en direct de toute l'installation, le journal d'événements et le rapport d'assistance que vous copiez quand quelque chose ne va pas (section 19).

Chat d'assistance (bulle flottante)

En bas à droite de chaque écran se trouve une bulle de chat 💬 pour parler directement à l'assistance : conversations par sujet, historique, et un avis indiquant si l'assistance est disponible ou absente. Seul ce que vous écrivez est partagé — jamais les données de vos clients.

Paramètres

Langue de l'application (7 langues), Design du widget (le modèle de style pour toute la boutique — section 13), synchronisation manuelle des remises et accès développeur.

4Anatomie de l'éditeur

Chaque type partage le même éditeur ; seule la section produits et tarification change. Un bundle tout neuf ressemble à ceci :

4.1 Éléments de base

Nom du bundle

Interne. Vous seul le voyez ; il sert à le retrouver dans votre liste.

Titre pour la boutique

Ce que voit le client comme nom de l'offre dans le panier et au paiement. Il est traduisible. C'est aussi le texte de la ligne de remise (tronqué à 100 caractères).

Texte du badge

Un badge court optionnel (« Meilleur choix ») que votre thème peut afficher comme mise en avant.

4.2 Programmation

Dates de début et de fin optionnelles. Vide = l'offre entre en vigueur à la publication et n'expire jamais. Un bundle publié en dehors de sa période arrête d'appliquer la remise automatiquement et l'applique à nouveau une fois revenu dans la période, sans que vous ayez rien à toucher.

4.3 Produits

Selon le type choisi, vous sélectionnez des produits spécifiques (et, pour chaque produit, vous pouvez ne cocher que certaines de ses variantes) ou une collection. La portée « n'importe quel produit de la boutique » n'existe que pour le cadeau pour tout achat, comme condition. Le sélecteur est celui, standard, de Shopify :

4.4 Prix

Chaque type possède sa propre section (pourcentage, montant, prix fixe, paliers, récompense…). C'est documenté dans le chapitre de chaque type. Dans tous les cas, le prix facturé est calculé par Shopify au paiement à partir de la configuration publiée : ce que montrent les blocs est à titre indicatif.

4.5 Abonnements

Par défaut, un client ne peut pas acheter un article de bundle en abonnement (cela protège le paiement contre le mélange de la tarification d'abonnement avec les remises de bundle). Dans les types où cela a du sens (mix & match, composez votre box et cadeau pour tout achat), il existe une option avancée à activer, « Autoriser les abonnements dans ce bundle (avancé) » ; l'activer fait apparaître dans l'éditeur un avis rappelant ce que cela implique.

4.6 Le panneau latéral droit (et deux sections du corps)

Outre Enregistrer (et Enregistrer comme brouillon sur un bundle pas encore publié), avec la barre Modifications non enregistrées / Enregistrer / Annuler en haut, l'éditeur organise le reste ainsi :

Statut + action (panneau)

Publier (ou Mettre à jour le bundle s'il est déjà publié) et Mettre en brouillon. Publier met l'offre en ligne ; mettre en brouillon la retire tout en conservant toute la configuration.

Mode test (corps)

Cochez « Publier en mode test » pour essayer le bundle sans l'exposer à vos clients. Les widgets s'affichent uniquement dans l'éditeur de thème — ouvrez-y le modèle de produit et le bundle apparaît exactement à sa place. Ils n'apparaissent jamais sur votre boutique, pas même via le lien d'aperçu d'un thème brouillon. Tant que le bundle est en mode test, la remise n'est calculée que pour les clients portant l'étiquette combora-test ; pour tous les autres, le bundle pourrait tout aussi bien ne pas exister. Pour parcourir le paiement en entier, ajoutez cette étiquette à votre propre client de test (Admin → Clients) et connectez-vous en tant que ce client sur la boutique. Décochez la case et cliquez sur Mettre à jour le bundle et il passe en ligne, s'appliquant à quiconque remplit les conditions. Dans la liste, un bundle en mode test porte le badge Mode test.

Visibilité dans le catalogue (corps)

Bundles fixes uniquement : si le produit parent du bundle apparaît dans votre catalogue ou non (section 5).

Avant de publier (panneau)

La checklist qui bloque la publication tant que l'essentiel n'est pas fait (titre, produits, prix…).

Ce que voit votre client (panneau)

Tant qu'il manque quelque chose à l'offre, cette carte explique ce qui manque et prévisualise le contenu. Une fois l'offre complète, la carte laisse place au véritable aperçu du widget sous Voir l'aperçu. Le rendu final dépend de votre thème.

Style de l'aperçu (panneau, uniquement sur les bundles déjà créés)

Indique le design actif du widget de ce bundle et propose Voir l'aperçu (le widget en taille réelle dans une fenêtre modale) et Personnaliser le design (l'atelier de design propre à ce bundle : préréglages, ordre des éléments et style par élément — section 13). Sur un bundle tout neuf, elle apparaît après le premier enregistrement.

Où cela s'affiche (panneau)

Le bloc de thème qui affiche ce type et le lien direct vers l'éditeur de thème.

Un bundle avec une programmation affiche aussi son badge de période (Programmé / Actif / Terminé) et le bouton Retirer la programmation pour revenir à « actif dès la publication ».

4.7 Avis que l'éditeur peut afficher

• Chevauchement : si les produits du bundle figurent déjà dans d'autres bundles publiés, une bannière avertit : « Seule la meilleure offre par ligne s'applique au paiement : les bundles ne se cumulent pas ». Ce n'est pas une erreur — c'est une information (voir section 14).
• Aucune économie / prix à 0 : dans un bundle fixe avec un prix de bundle, si le prix choisi ne fait économiser rien (ou est à 0), l'éditeur le signale avant que vous ne publiiez.
• Réservoir vide : une collection sans produit éligible apparaît comme une note dans l'aperçu et, si vous essayez de publier, comme une erreur avec l'explication.

4.8 Modifier un bundle publié

Lorsque vous modifiez un bundle publié, vos changements sont enregistrés sans atteindre votre boutique. L'éditeur affiche votre modification, vos clients continuent de voir la version publiée à son prix publié, et le bundle est signalé Modifications non publiées dans votre liste. Appuyez sur « Mettre à jour le bundle » pour les publier, ou abandonnez-les depuis l'avis dans l'éditeur. Vous pouvez ainsi préparer les changements tranquillement. « Mettre en brouillon » retire l'offre de la boutique immédiatement ; la republier la restaure exactement telle qu'elle était.

5Bundle fixe

Un ensemble fermé de produits vendus comme une seule unité. C'est le seul type qui crée aussi un produit achetable en un clic dans votre catalogue : un produit « parent » (un bundle natif Shopify) dont les composants se développent automatiquement au paiement.

5.1 Configuration

1. Produits : ajoutez les composants (variantes spécifiques) et leur quantité respective. Maximum 30 composants par bundle.
2. Prix — deux modes mutuellement exclusifs :
   • Prix de bundle fixe : vous saisissez le prix total (par ex. $1,299.00). L'économie est calculée par rapport à la somme des composants.
   • Appliquer une remise : un pourcentage ou un montant déduit de la somme des composants.
3. Visibilité dans le catalogue : les bundles fixes sont de vrais produits Shopify, vous décidez donc si le bundle apparaît aussi dans votre catalogue ou n'est accessible que depuis le widget :
   • Masqué — uniquement depuis le widget (par défaut) : le bundle n'apparaît pas dans les collections, dans la recherche de la boutique, ni dans les recommandations. Sa page produit reste active pour que le bouton du widget fonctionne.
   • Visible — un produit de catalogue normal : il apparaît dans les collections et la recherche comme n'importe quel autre produit.
4. Publier. À la publication, Combora crée (ou met à jour) le produit parent dans votre catalogue — et, si le pack n'a pas encore d'image, y copie celle du premier composant, dans les DEUX modes de visibilité (un pack masqué apparaît quand même dans le panier, au paiement et dans les emails de commande). Elle ne remplace jamais une image que vous avez définie ; vous pouvez la changer à tout moment sous Admin → Produits.

5.2 Ce que voit votre client

5.3 Détails et limites de ce type

• Les composants doivent être des variantes en stock ; le produit parent hérite de la disponibilité.
• Le produit parent se gère lui-même : mettre le bundle en brouillon ou le supprimer le retire de la boutique (vérifié en rédigeant ce manuel). Ne le supprimez pas à la main.
• Par défaut, le parent est masqué du catalogue. Avant que cette option n'existe, il apparaissait dans /collections/all sous forme de fiche sans image ; les bundles déjà publiés ont été basculés automatiquement sur « Masqué ». Si vous préférez l'ancien comportement, basculez-le sur Visible.
• Maximum 30 composants. Le prix fixe est réparti entre les composants avec un arrondi exact (la somme des parties égale toujours le total).
• Le bundle fixe s'applique aussi si le client ajoute les composants séparément dans les quantités exactes — le paiement les regroupe et les remise de la même façon.

6Mix & match

Le client choisit au moins N articles dans un groupe et tout le groupe ressort remisé.

6.1 Configuration

1. Produits : le groupe éligible peut être des produits spécifiques — en ne cochant, si vous le souhaitez, que certaines variantes de chacun dans le sélecteur — ou une collection (qui se met à jour toute seule).
2. Quantité : le nombre minimum d'articles pour se qualifier, et optionnellement un maximum (au-delà du maximum, les articles supplémentaires sont payés plein tarif).
3. Remise : un pourcentage ou un montant, appliqué à chaque article éligible dans le panier une fois le minimum atteint.

6.2 Ce que voit votre client

6.3 Détails de ce type

• Un panier sous le minimum n'est pas bloqué : le client paie plein tarif jusqu'à ce qu'il se qualifie.
• Avec un maximum défini, le sélecteur cesse d'accepter des sélections une fois le plafond atteint, et dans le panier seules les premières unités jusqu'au maximum sont remisées.
• Les quantités comptent par unités : 3 unités du même produit éligible se qualifient aussi pour un minimum de 3.

7Remise sur volume

Des paliers de prix par quantité : « achetez au moins 2 → 10%, au moins 4 → 20% ». Le palier se décide par produit : la quantité de chaque produit éligible dans le panier détermine son propre palier, et le palier atteint s'applique aux unités de ce produit. Exemple avec « 4+ → 20% » : 4 unités de la même planche → 20% de moins sur les 4 ; mais 2 unités d'une planche + 2 d'une autre → chaque produit se situe dans le palier 2+ (10%), pas dans le palier 4+. Les quantités de produits différents ne s'additionnent pas entre elles.

7.1 Configuration

1. Produits : produits spécifiques ou une collection (comme pour le mix). Si vous ne voulez que certaines variantes d'un produit, cochez-les dans le sélecteur au moment de le choisir.
2. Paliers : chaque palier est « Achetez au moins N » + une remise (pourcentage ou montant). Ajoutez-en autant que nécessaire avec « Ajouter un palier » (jusqu'à 50).

7.2 Ce que voit votre client

7.3 Détails de ce type

• Seul le palier le plus élevé atteint s'applique (les paliers ne s'additionnent pas).
• Les paliers peuvent mélanger les types de valeur (certains en %, d'autres en montant).
• Un montant de remise fixe est réparti entre les lignes proportionnellement et exactement.

8Achetez X, obtenez Y (BOGO)

Achetez X unités et les Y unités suivantes bénéficient d'une récompense. La récompense peut être gratuite (100%), un pourcentage, un montant de remise ou un prix fixe par unité.

8.1 Configuration

8.2 Ce que voit votre client

8.3 Détails de ce type

• L'offre se répète par blocs entiers : avec « 2+1 », 6 unités = 2 gratuites ; 5 unités = 1 gratuite.
• Le bloc de thème qui l'affiche est Combora volume table (il présente le « achetez X obtenez Y » comme une table d'économies).
• La récompense « prix fixe » facture exactement ce prix pour chaque unité récompensée.

9Cadeau pour tout achat (GWP)

Ajoute un produit cadeau (à $0.00) automatiquement lorsque le panier remplit la condition, et le retire s'il cesse de la remplir. C'est le type le plus automatisé : l'app embed Combora Gift gère le cadeau sans que le client n'ait rien à faire.

9.1 Configuration

1. Le cadeau : une variante spécifique qui s'ajoute quand le client se qualifie.
2. Condition à débloquer — quatre options :
   • Par dépense minimale : le panier atteint un montant (par ex. $1,000).
   • Par nombre d'articles : il atteint N unités.
   • Dépense et quantité (les deux) : les deux sont exigées.
   • En transportant une combinaison de produits : une liste spécifique d'articles (de 2 à 5 ; une unité de chacun) qui doivent tous être dans le panier.
3. Ce qui compte pour la condition : n'importe quel produit de la boutique, des produits spécifiques, ou des collections.

9.2 Ce que voit votre client

La barre a quatre états et, dès le panier vide, elle nomme le cadeau et ce qui compte : avant que le client ne commence, elle énonce la règle (« dépensez $1,000 sur cette planche et recevez le fart gratuitement »), à mi-chemin elle dit ce qu'il manque, au franchissement du seuil elle annonce le cadeau par son nom, et si le client le retire à la main elle le dit au lieu de rester sur « application en cours ». Quand plus de trois produits comptent, la barre dit produits éligibles et ajoute un volet « Quels produits comptent ? » qui les liste.

9.3 Détails et protections de ce type

• Le cadeau lui-même ne compte pas dans la dépense qualifiante.
• Le seuil se mesure sur le prix catalogue de ce qui compte, pas sur ce que le client finit par payer : une autre offre qui réduit ces mêmes lignes ne l'entame donc jamais. La barre, le cadeau automatique et le paiement lisent le même nombre.
• Si le client retire le cadeau à la main, l'application le respecte et ne le rajoute pas durant cette session ; la barre du panier le dit clairement (« Cadeau retiré ») au lieu de rester sur « en cours d'application ».
• Si vous retirez l'offre (mise en brouillon, fin de la période) alors que des paniers ouverts avaient déjà le cadeau, le moteur retire lui-même cette ligne orpheline dès que le panier bouge à nouveau — elle ne se transforme jamais en charge.
• Si le cadeau vient à manquer, l'offre ne l'ajoute simplement pas (elle ne bloque pas l'achat).
• Protection anti-facturation : une validation au paiement empêche de payer un cadeau qui est marqué comme tel mais qui arrive avec un prix — le client ne paie jamais par erreur un article marqué comme cadeau. La validation agit uniquement au paiement, jamais pendant la navigation.
• Quand « ce qui compte » est des collections, l'application résout les produits de la collection au moment de la publication (et les rafraîchit chaque nuit, ou immédiatement si vous republiez — les deux vitesses de la section 4.3), de sorte que la barre de progression et le cadeau automatique fonctionnent tout comme avec des produits spécifiques. La seule exception : une collection énorme (plus de ~150 produits) ne peut pas être anticipée depuis le navigateur — la barre ne s'affiche pas pour cette offre, mais le cadeau et le prix restent corrects (le serveur les décide).
• Un cadeau dont « ce qui compte » est n'importe quel produit de la boutique peut être annoncé avec le bloc Combora gift offer sur chaque page produit : quand vous choisissez cette portée, l'éditeur affiche la case « Afficher cette offre de cadeau sur chaque page produit ». Désactivée (par défaut), l'offre n'est visible que dans le panier — la barre de progression et le cadeau automatique fonctionnent de la même façon ; activée, elle est aussi annoncée avec une fiche sur chaque page produit (l'offre n'a pas de produits spécifiques à cocher, donc le bloc la lit depuis l'index publié de la boutique). L'exception délibérée reste la page du produit cadeau lui-même : un prix n'est pas un hameçon.

10Composez votre box

Le client remplit une box de taille fixe (par ex. 3 articles) avec ce qu'il choisit dans un groupe. Chaque box complète est facturée avec une remise ou à un prix de box fermé.

10.1 Configuration

10.2 Ce que voit votre client

Elle utilise le même bloc Combora mix & match et le même sélecteur avec un compteur que la section 6 : « sélectionnez 3 », un compteur de progression, un CTA avec la quantité. La différence est le calcul : ici les box sont facturées par box complète — avec une box de 3, six articles font deux box ; sept articles font deux box plus un article au plein tarif.

10.3 Détails de ce type

• Groupe éligible : produits spécifiques (avec leurs variantes, si vous n'en cochez que certaines) ou une collection (le sélecteur visuel s'affiche avec toute portée, comme pour le mix — avec les collections la liste est résolue au moment de la publication et rafraîchie chaque nuit).
• Le prix de la box est réparti entre les articles exactement ; avec des devises à 0 décimale (JPY) ou à 3 décimales (BHD), la répartition respecte la devise.
• Elle prend en charge l'option d'abonnements (section 4.5).

11Compléments (fréquemment achetés ensemble)

Un produit principal suggère des produits complémentaires ; si le client prend l'ensemble, il obtient une remise. C'est le classique « fréquemment achetés ensemble » sur la page produit.

11.1 Configuration

11.2 Ce que voit votre client

11.3 Détails de ce type

• La remise s'applique dès que le produit principal et au moins un complément sont dans le panier ; elle couvre les lignes de l'ensemble.
• Le bloc peut aussi être ajouté au modèle de panier comme dernière incitation à la vente croisée.
• Les compléments en rupture de stock apparaissent désactivés avec leur avis, et ne sont jamais pré-cochés.

12Combo

Le type avancé : il cumule deux sous-offres ou plus (de n'importe lequel des autres types) en un seul bundle. La différence clé par rapport à publier des bundles séparés : à l'intérieur d'un combo, les sous-offres s'additionnent — le client peut obtenir la remise sur volume et le cadeau en même temps.

12.1 Configuration

Chaque ligne se déploie sur place avec le chevron, et la sous-offre s'édite en ligne : ses propres produits, ses propres paliers ou sa récompense. Chaque sous-offre n'affecte que ses propres produits.

12.2 Ce que voit votre client

Un combo n'est pas mis en avant sous forme de fiche dans le bloc Combora bundle : ce bloc liste les bundles fixes, qui ont un prix et un bouton, et un combo n'a ni l'un ni l'autre. Chaque sous-offre est mise en avant par son propre bloc — la table de volume pour une sous-offre de volume, la barre de cadeau pour une sous-offre de cadeau — et le combo montre son effet complet dans le panier, où chaque partie agit avec son propre badge : la remise sur volume sur ses lignes et le cadeau ajouté automatiquement à $0.00.

Mesuré dans la boutique de démonstration sur un combo qui cumule « 2 planches ou plus → 15% de remise » et « un bonnet offert dès $900.00 de cette planche » : deux planches passent de $1,040.00 à $850.00 — les 15% et le bonnet à $0.00 — et trois passent de $1,540.00 à $1,275.00. Deux bundles séparés ne feraient jamais les deux sur la même ligne ; à l'intérieur d'un combo les sous-offres s'additionnent (section 14).

12.3 Détails de ce type

• Les sous-offres s'additionnent à l'intérieur du combo, mais le combo est en concurrence dans son ensemble avec les autres bundles selon la règle de la meilleure offre par ligne.
• Le cadeau dans une sous-offre GWP utilise le même moteur d'ajout automatique que le type cadeau.
• Limite de taille : l'ensemble aplati des produits du combo ne peut pas dépasser 50 entrées (l'éditeur l'affiche : « Utilise X sur 50 »).
• L'éditeur possède une fenêtre modale « Comment fonctionnent les combos » avec un exemple guidé, et chaque sous-offre définit « Produits auxquels cette offre s'applique » — une sous-offre sans produits spécifiques affiche un avertissement car elle ne pourra rien tarifer.
• Une sous-offre BOGO à l'intérieur d'un combo propose une récompense en pourcentage ou en montant (le « prix fixe par unité » est exclusif au BOGO autonome).

13Concevoir le widget

Les blocs de Combora sont livrés avec une apparence qui s'adapte à tout thème, mais vous pouvez les concevoir depuis l'application, sans toucher au CSS : choisissez un style, réordonnez et masquez des éléments, et ajustez couleurs, tailles et formes élément par élément. Le tout avec un aperçu qui utilise le même moteur de rendu que votre boutique, de sorte que ce que vous voyez est ce qui sera publié.

13.1 Deux endroits où concevoir

Un bundle qui n'a rien touché affiche l'avis « Ce bundle suit le modèle de widget de votre boutique ». Dès que vous choisissez un préréglage là-bas, ce bundle prend son propre chemin.

13.2 Les styles (préréglages)

Modèle de la boutique

Uniquement dans le design d'un bundle : il suit ce que vous avez défini dans Paramètres. C'est la valeur de départ. S'il n'y a pas encore de modèle, les réglages du bloc dans l'éditeur de thème s'appliquent.

Éditeur de thème

Les propres réglages du bloc dans votre éditeur de thème l'emportent (accent, coins, mode de style). C'est le comportement classique, celui que vous aviez avant que l'atelier n'existe.

Combora

Le look soigné de Combora : une carte avec son propre arrière-plan, ses bordures et ses ombres. Cohérent dans n'importe quel thème.

Comme le thème

Décoration minimale : la typographie et les couleurs de votre thème dominent. Pour les thèmes à forte personnalité.

Sans style

Balisage propre, sans décoration, pour que votre développeur écrive son propre CSS (éditeur de thème → CSS personnalisé). Les points d'ancrage sont la classe .combora-w et les variables --combora-*.

Personnalisé

Ouvre les contrôles ci-dessous : disposition, style global et ajustement fin par élément.

13.3 Disposition : réordonner et masquer

Avec le préréglage Personnalisé, Disposition apparaît : une liste des éléments du widget que vous pouvez glisser (ou déplacer avec les flèches) pour changer leur ordre, plus une icône œil pour masquer les éléments optionnels.

Les éléments dépendent du type de bundle, car chaque type dessine un widget différent :

13.4 Style global et ajustement fin

Le style global change tout le widget d'un coup : couleur d'accent, arrière-plan de la carte, couleur du texte, coins (nets / doux / arrondis), ombre (aucune / douce / moyenne) et densité.

L'ajustement fin par élément ouvre chaque élément séparément — titre, prix, économie, badge, bouton, carte, vignettes, étiquettes — avec ce qui a du sens pour chacun : taille, graisse, couleur, majuscules, marge intérieure, forme, couleur de bordure, couleur du prix barré… Chaque contrôle possède un « Revenir au thème » pour annuler seulement cet ajustement, et en bas se trouve une « Réinitialiser toute la personnalisation ».

• Si vous ne définissez pas l'Économie, elle suit le style du Badge.
• La couleur du texte du bouton ne peut pas être choisie : elle est dérivée automatiquement par contraste avec l'arrière-plan que vous choisissez, afin qu'elle ne devienne jamais illisible.
• Les valeurs sont bornées à des plages raisonnables : vous ne pouvez pas saisir une taille qui casse le widget sur mobile.

13.5 L'aperçu (et ce qu'il n'est PAS)

À droite se trouve un panneau marqué « Aperçu uniquement ». La différence compte :

• Gauche = votre design. Ce que vous ajustez là est enregistré et va sur la boutique.
• Droite = la loupe. Arrière-plan de l'aperçu (clair / sombre / une couleur personnalisée), taille de texte de base, largeur de l'emplacement (une colonne produit étroite vs. une section large) et une approximation de votre typographie. Il sert à vérifier que votre design tient dans différents endroits. Il ne change rien dans votre boutique ni dans votre design.

Et dans le panneau de l'éditeur de bundle, la carte « Style de l'aperçu » indique quel design est actif (« Design actif : Combora ») et propose deux boutons : Voir l'aperçu, qui ouvre le widget en taille réelle dans une fenêtre modale (« Voici à quoi il ressemblera dans votre boutique »), et Personnaliser le design, qui entre dans l'atelier de ce bundle. La vraie typographie et l'arrière-plan viennent de votre thème, donc pour la validation finale, regardez le widget dans l'éditeur de thème.

14Combiner les bundles entre eux

Vous pouvez publier autant de bundles que votre forfait le permet, même sur les mêmes produits. Les règles de coexistence sont fixes et prévisibles :

1. La meilleure offre par ligne. Pour chaque article du panier, Shopify applique l'offre qui remise le plus cet article. Deux bundles ne s'additionnent jamais sur la même ligne.
2. Des bundles différents peuvent coexister dans le même panier — chacun sur ses propres lignes. Une remise mix sur les planches et un cadeau basé sur la dépense peuvent s'appliquer en même temps parce qu'ils agissent sur des lignes différentes.
3. En cas d'égalité, le bundle le plus ancien gagne (le premier que vous avez créé).
4. L'exception est le combo : ses sous-offres s'additionnent entre elles (section 12).

Et les remises qui ne viennent pas de Combora ? La règle ci-dessus gouverne les packs de Combora entre eux. Avec les remises tierces, c'est Shopify qui décide, et nous l'avons vérifié en boutique : deux remises produit (un pack Combora et une remise automatique ou un code produit à vous) ne s'additionnent jamais sur le même article — Shopify n'applique que la plus avantageuse des deux, même si les deux sont marquées combinables ; elles peuvent coexister sur des lignes différentes de la même commande. Une remise de commande (par exemple un code de −10 % sur toute la commande) se soustrait bien ensuite, sur les prix déjà remisés — le comportement standard de Shopify avec n'importe quelle app.

Un exemple numérique réel (vérifié en boutique)

Dans la boutique de démonstration, un produit appartient délibérément à deux bundles : la planche qui est un composant du bundle fixe est aussi le sujet du bundle de volume. Seule, elle prend le palier de volume que sa quantité lui vaut ; avec l'autre composant du bundle fixe, dans les quantités exactes, le bundle fixe devient lui aussi candidat et la ligne garde la meilleure des deux. Même produit, deux bundles, un prix par ligne — jamais les deux.

15Création en masse

Depuis la galerie Créer un bundle, deux parcours permettent de créer beaucoup de bundles à la fois. Les deux créent des brouillons : rien n'atteint la boutique tant que vous n'avez pas vérifié et publié.

15.1 Générer à partir d'une collection

1. Choisissez la collection.
2. Choisissez le modèle : « Un multipack par produit » (un bundle fixe de N unités pour chaque produit) ou « Un seul bundle pour toute la collection ».
3. Configurez les unités et la remise, puis cliquez sur Créer les brouillons.

Ce que chaque modèle crée réellement

Un multipack par produit parcourt la collection et crée un brouillon de bundle fixe par produit : N unités de la première variante de ce produit (par ordre de position), avec la remise choisie appliquée à la somme. Chaque brouillon est un bundle fixe normal — ouvrez-le pour changer la variante, passer à un prix de pack fermé, ajouter un badge… — et quand vous le publiez, il devient son propre produit achetable en un clic, comme n'importe quel bundle fixe (section 5).

Un seul bundle pour toute la collection crée exactement un brouillon du type flexible que vous choisissez (volume, mix & match, composez votre box ou achetez X, obtenez Y) dont le réservoir éligible est la collection elle-même. L'appartenance suit votre catalogue : le réservoir est résolu au moment de la publication et rafraîchi chaque nuit (ou immédiatement si vous republiez), de sorte que les produits que vous ajouterez plus tard à la collection rejoignent l'offre sans toucher au bundle.

Des produits sont ignorés, et la bannière de résultat vous l'indique, lorsqu'ils ne sont pas Actifs dans votre catalogue, lorsqu'ils n'ont aucune variante achetable — et lorsqu'ils sont eux-mêmes des produits pack Combora : un pack généré n'imbrique jamais un autre pack.

Exemples concrets

Le même écran, sept configurations, et exactement ce que chacune produit :

15.2 Importer depuis un CSV

Pour les gros catalogues ou pour migrer depuis une autre application. La page inclut la référence complète du format, un modèle téléchargeable avec un exemple par type et un bouton d'exportation (il télécharge tous vos bundles dans le même format, prêt à être réimporté dans une autre boutique).

• Types importables : fixed, volume, mix_and_match, build_a_box, bogo (les types avec un cadeau, une ancre ou des sous-offres se créent dans l'éditeur).
• Références par handle de produit ou de collection, ou par GID Shopify.
• Dans components (fixe uniquement) : handle:quantity séparés par |.
• Jusqu'à 200 lignes par import ; un fichier plus gros est tronqué et vous en êtes averti.

16Gestion au quotidien

16.1 La liste

Recherche par nom, filtre par statut et, sur chaque ligne : Dupliquer (crée une copie en brouillon), Publier / Mettre en brouillon et Supprimer. La date sur chaque ligne est la dernière mise à jour (survolez pour l'infobulle).

16.2 Actions groupées

16.3 Le cycle de vie d'un bundle

Brouillon

Invisible pour la boutique. Modifiable sans limite.

Publié

L'offre est active (dans sa période de programmation). Modifier ne change rien en direct tant que vous n'appuyez pas sur Mettre à jour le bundle.

Mettre en brouillon

Retire l'offre immédiatement ; la configuration est conservée intacte pour pouvoir republier.

Supprimer

Supprime le bundle et retire sa remise (et le produit parent, s'il s'agissait d'un bundle fixe). C'est irréversible. Les statistiques des commandes passées sont conservées.

16.4 Ce que Combora fait toute seule, pendant que vous dormez

Quatre processus automatiques maintiennent votre boutique à jour sans que vous ayez rien à faire. Vous n'avez pas besoin de les configurer ou de les surveiller — ils sont documentés ici pour que vous sachiez pourquoi les choses se réparent d'elles-mêmes :

17Statistiques

Si vous vendez en plusieurs devises, un sélecteur de devise se trouve à côté des indicateurs : les montants sont affichés dans la devise choisie (les compteurs de commandes sont globaux).

Sous les indicateurs se trouvent trois graphiques pour la période choisie, tous avec une marque par jour et une infobulle :

• Commandes avec un bundle dans le temps — des barres, avec la valeur imprimée au-dessus des barres qui ont des données.
• Revenu attribué par jour — une ligne, pour voir la tendance.
• Économies accordées par jour — des barres : combien de remise vos bundles ont donné chaque jour.

18Paramètres et forfaits

18.1 Paramètres

• Langue de l'application : 7 langues (anglais, espagnol, français, allemand, italien, portugais, néerlandais). Cela affecte l'admin ; ce que voit votre client suit la langue de votre thème/marché.
• Design du widget : Modifier le modèle du widget ouvre l'atelier de design pour toute la boutique — le style que chaque bundle hérite (section 13). Enregistrer ici resynchronise les bundles publiés.
• Synchroniser les remises : vous n'avez pas besoin d'appuyer dessus — tout se synchronise tout seul quand vous publiez. C'est là comme filet de sécurité : si un bundle cessait un jour de remiser, cela régénère la remise Shopify à partir de tous vos bundles publiés. C'est sans risque de l'utiliser aussi souvent que vous le voulez, et s'il n'y avait rien à réparer, cela vous le dit : Tout était déjà à jour.
• Accès développeur : les données publiques que votre thème peut lire (annexe 22). La documentation du contrat est ouverte sur tous les forfaits.

18.2 Forfaits

Tarification fixe : nous ne prenons jamais de pourcentage sur vos ventes, et le prix ne dépend pas de votre forfait Shopify — une boutique Basic et une boutique Plus paient le même prix.

• Gratuit ($0/mois) : jusqu'à 3 bundles publiés à la fois (les brouillons ne comptent pas) avec les 8 types inclus. Quand vous essayez de publier le 4e, l'application le bloque avec l'avis correspondant : mettez-en un autre en brouillon ou passez à un forfait supérieur. Sur le forfait gratuit, les blocs affichent un discret badge Powered by Combora.
• Pro ($14.99/mois) : bundles publiés illimités et pas de badge.
• Plus ($39.99/mois) : tout ce qui est dans Pro, plus une assistance prioritaire, l'import/export CSV en masse (jusqu'à 200 bundles par fichier) et un support d'intégration directe pour votre développeur (boutiques headless et thèmes personnalisés).

La facturation passe par Shopify (Managed Pricing) — elle se gère et s'annule depuis la page Forfaits elle-même. Les forfaits payants incluent un essai gratuit de 7 jours, et si vous annulez, vous conservez le forfait jusqu'à la fin du cycle déjà payé. Les boutiques fondatrices (les 100 premières installations) conservent le produit complet gratuitement pour toujours.

19Diagnostic et assistance

Diagnostic (le deuxième onglet d'Aide) est votre premier arrêt quand quelque chose ne colle pas — et ce que l'assistance vous demandera si vous ouvrez un ticket. Combora enregistre automatiquement, par boutique, tout ce qui échoue en coulisses (sur le serveur et dans votre boutique en ligne) même quand le client ne le voit jamais, et ce panneau le met à votre portée. Il ne stocke aucune donnée client.

19.1 Vérifications de santé

L'état en direct de ce que l'assistance demande en premier, vérifié auprès de Shopify à chaque chargement :

19.2 Journal d'événements

Chaque entrée est quelque chose qui s'est produit et a été enregistré : un échec lors de la publication, un cadeau que Shopify a refusé d'ajouter (avec la raison exacte), une remise qui est entrée en collision avec une autre, un webhook qui a échoué… Filtrez par niveau (Info = attendu mais pertinent, comme la limite du forfait ; Avertissement ; Erreur) et par zone (publication, remises, forfait et facturation, boutique, synchronisation…). Un journal vide est bon signe : il ne se remplit que lorsque quelque chose ne va pas. Les événements sont conservés 30 jours.

19.3 Le rapport d'assistance

Un document unique avec tout ce qu'il faut pour diagnostiquer votre boutique en une fois : les vérifications de santé, votre forfait et votre configuration (sans données sensibles), le statut de publication de chaque bundle et les derniers événements. Quand vous contactez l'assistance, cliquez sur Copier le rapport (ou Télécharger comme fichier) et joignez-le au ticket — avec cela, quiconque vous aide voit exactement ce qui s'est passé sans demander de captures d'écran ni d'accès.

• Le rapport n'inclut aucune donnée client et aucune clé : seulement la santé, la configuration des bundles et les événements techniques.
• Si le bouton de copie ne fonctionne pas dans votre navigateur, le texte reste sélectionné — appuyez sur Ctrl+C (Cmd+C sur Mac) — ou utilisez le téléchargement.

20Limites et règles importantes

La référence unique pour les limites, vérifiée par rapport au code de l'application :

Règles monétaires (toujours exactes)

• Les pourcentages tronquent la remise vers le bas (elle n'est jamais arrondie en faveur d'une facturation plus élevée).
• Les montants et prix fixes sont répartis entre les lignes avec un reste exact : la somme des parties égale toujours le total.
• Les décimales dépendent de la devise de votre boutique (JPY sans aucune, BHD avec trois…) — deux décimales ne sont jamais supposées.
• Le prix facturé est calculé par Shopify au paiement à partir de la configuration publiée. Ce que montrent les blocs du thème est à titre indicatif.

Multi-devises (Shopify Markets)

Si vous vendez en plusieurs devises, il n'y a rien à configurer : vous définissez les prix, les seuils et les remises dans la devise de votre boutique, et Combora fait le reste. Un client qui achète dans une autre devise voit les montants du widget convertis dans la sienne (le seuil du cadeau, le prix du bundle, l'économie de chaque palier), et au paiement la remise est convertie au taux de change de Shopify du moment — le même qui convertit les prix de vos produits. La règle d'or tient toujours : ce que le client voit annoncé est exactement ce que le paiement lui facture, dans sa devise.

Autres règles

• Les abonnements sont bloqués sur les lignes de bundle à moins que vous ne l'activiez explicitement (section 4.5).
• Un cadeau GWP n'est pas annoncé sur la propre page du produit cadeau (un prix n'est pas un hameçon).
• Les bundles publiés en dehors de leur période de programmation n'appliquent aucune remise (ils se réactivent tout seuls).

21Dépannage

Je ne vois pas l'offre sur ma boutique

① Le bundle est-il Publié (pas un brouillon) et dans sa période ? ② Avez-vous ajouté le bon bloc au modèle (la carte Où cela s'affiche dans l'éditeur) ? ③ Si vous avez modifié un bundle publié, avez-vous appuyé sur Mettre à jour le bundle ?

Le cadeau ne s'ajoute pas de lui-même

① L'app embed Combora Gift est-elle activée ? ② Le panier remplit-il la condition en ne comptant que ce qui se qualifie (le cadeau ne compte pas) ? ③ Le client l'a-t-il retiré à la main durant cette session ? ④ Le cadeau est-il en stock ?

La remise du panier n'est pas celle attendue

Rappelez-vous la règle : seulement la meilleure offre par ligne. Si deux bundles sont en concurrence pour le même article, celui qui remise le plus gagne (et en cas d'égalité, le plus ancien). L'addition ne se produit qu'à l'intérieur d'un combo.

L'application dit : Vous avez une autre remise automatique active

C'est une information, pas une erreur. Cela signifie que vous avez vos propres remises produit automatiques dans Shopify. Là où un bundle Combora et l'une de ces remises portent sur le même produit, Shopify n'applique que la meilleure des deux — cumuler deux remises produit sur le même article nécessite Shopify Plus. C'est une règle de Shopify, pas de Combora. Vos bundles se combinent bien avec vos remises de commande et de livraison, et avec les remises produit qui portent sur d'autres produits. L'avis nomme la remise en chevauchement spécifique pour que vous sachiez laquelle regarder.

J'ai publié et cela dit limite de forfait

Le forfait Gratuit autorise 3 bundles publiés à la fois. Mettez-en un autre en brouillon ou passez à un forfait supérieur.

La barre de progression du cadeau n'apparaît pas

Elle s'affiche dans le modèle de panier (le bloc Combora gift progress) et uniquement pour les offres dont le critère peut être évalué dans le navigateur. Avec des collections comme critère, cela fonctionne aussi, car l'application résout les produits de la collection quand vous publiez ; la seule exception est une très grande collection (plus de ~150 produits), où la barre ne s'affiche pas même si le cadeau fonctionne toujours.

Le sélecteur à cases à cocher n'apparaît pas dans mix / box

Le sélecteur s'affiche avec toute portée : avec des variantes spécifiques, il affiche exactement ces cases à cocher, et avec des produits ou une collection la liste est résolue quand vous publiez (et rafraîchie chaque nuit, ou immédiatement si vous republiez). S'il est encore vide, le groupe éligible n'a aucun produit achetable — vérifiez la note d'aperçu dans l'éditeur. Dans tous les cas, le client peut ajouter des produits comme d'habitude et la remise se déclenche en se qualifiant.

Erreurs lors de l'import d'un CSV

Chaque ligne échouée est listée avec sa raison. Corrigez ces lignes et relancez avec seulement celles-ci — les bonnes lignes ont déjà été créées.

Je soupçonne qu'une remise est restée orpheline

Paramètres → Synchroniser les remises répare l'état. Ne modifiez jamais à la main la remise Combora dans la section Remises de Shopify.

22Annexe pour développeurs : le contrat public

Combora publie les données de vos bundles dans votre boutique sous forme de metaobjects et metafields sous l'espace de noms combora, lisibles publiquement depuis la boutique. N'importe quel développeur peut construire une interface entièrement personnalisée en lisant ces données depuis Liquid ou la Storefront API — sans appeler aucune API de l'application. Ce contrat est versionné et uniquement additif (version actuelle : public.v1) : les champs existants ne sont jamais renommés ni retypés.

22.1 Ce qui est créé à l'installation

L'installation provisionne les définitions (les schémas) — visibles sous Paramètres → Metafields et metaobjects et sous Contenu → Metaobjects :

• Metaobjects : combora_bundle (le bundle), combora_component (chaque ligne de composant) et combora_tier (chaque palier de volume/seuil). Les trois avec un accès storefront PUBLIC_READ, publiables et traduisibles.
• Metafields de boutique : combora.index et combora.manifest (JSON, lecture publique), et combora.all_pdp_gwps (list.metaobject_reference → combora_bundle) : les cadeaux pour toute la boutique qui ont choisi d'être annoncés sur chaque page produit.
• Metafield de produit : combora.bundles (list.metaobject_reference → combora_bundle) — l'index inverse produit → ses bundles.

22.2 Ce qui se passe à la publication / mise à jour / retrait

22.3 combora_bundle champ par champ

22.4 Le descripteur eligible

Le réservoir éligible du bundle, avec la même forme dans tous les types :

{ "mode": "all" | "products" | "collections" | "variants",
  "variants":   ["gid://shopify/ProductVariant/…"],
  "products":   ["gid://shopify/Product/…"],
  "collections":["gid://shopify/Collection/…"],
  "resolved_count": 12, "total_count": 12, "truncated": false }

Seules les listes non vides sont incluses. Les trois clés de résolution sont informatives (sur les réservoirs de collection, elles indiquent combien de membres ont été matérialisés et si l'instantané a été tronqué) — vous pouvez les ignorer. Attention à la convention : le config du metaobject utilise le snake_case (gift_variant, min_qty), tandis que l'objet gwp dans l'index utilise le camelCase (giftVariant, minQty) — les mêmes données sur deux surfaces différentes.

Attention : les enfants role:"option" d'un réservoir de collection sont un instantané pris au moment de la publication ; l'appartenance en direct (et le prix) est toujours résolue par la Function au paiement.

22.5 combora.index et combora.manifest

shop.metafields.combora.index — la table de routage des bundles publiés (elle existe pour que vous n'ayez jamais à parcourir metaobjects.combora_bundle.values, que Liquid tronque silencieusement à 50) :

{ "schema": 1, "revision_highwater": 128, "generated_at": "…",
  "bundles": [
    { "id": "f3062319-9d6e-…", "handle": "combora-bundle-f3062319-9d6e-…", "type": "fixed",
      "gid": "gid://shopify/Metaobject/…", "status": "active", "revision": 42 }
  ] }

L'id est un identifiant textuel, pas un nombre. Seuls les bundles publiés et à l'intérieur de leur période de programmation sont annoncés, de sorte que l'index reste en phase avec le prix au paiement. Certaines entrées portent des champs supplémentaires : gwp (l'offre de cadeau, uniquement sur les bundles de type cadeau), gwps (les offres de cadeau d'un combo, dans l'ordre des sous-offres) et test (true si le bundle est en mode test : le JS de la boutique l'ignore sur le thème publié).

shop.metafields.combora.manifest — le descripteur de contrat qu'un outil lit une fois : contract_version, schema_version, le compteur de bundles et les GID des trois définitions. Il peut porter powered_by_badge: true, ce qui allume le badge Powered by Combora dans les blocs (uniquement sur les boutiques au forfait Gratuit ; ailleurs le champ est omis).

22.6 Le lire depuis Liquid

{%- comment -%} Sur une page produit : les bundles pour CE produit {%- endcomment -%}
{%- for bundle in product.metafields.combora.bundles.value -%}
  <h3>{{ bundle.title.value | escape }}</h3>
  {%- if bundle.badge_label.value != blank -%}
    <span class="badge">{{ bundle.badge_label.value | escape }}</span>
  {%- endif -%}
  <ul>
    {%- for component in bundle.components.value -%}
      {%- comment -%} label est optionnel : s'il manque, on retombe sur le titre de la variante puis
          sur le titre du produit. ATTENTION : si le produit n'est PAS publié sur le canal Boutique
          en ligne, sa référence ne se résout pas en Liquid et TOUS les repli renvoient blank —
          protégez le nom final ou vous afficherez un "1× " vide. {%- endcomment -%}
      {%- assign name = component.label.value -%}
      {%- if name == blank -%}{%- assign name = component.variant.value.title -%}{%- endif -%}
      {%- if name == blank or name == 'Default Title' -%}{%- assign name = component.variant.value.product.title -%}{%- endif -%}
      {%- if name != blank -%}
        <li>{{ component.quantity.value }}× {{ name | escape }}</li>
      {%- endif -%}
    {%- endfor -%}
  </ul>
{%- endfor -%}

{%- comment -%} Ou par handle direct, dans n'importe quel modèle {%- endcomment -%}
{%- assign bundle = metaobjects.combora_bundle['combora-bundle-{id}'] -%}

Les deux voies sont des lectures bornées (la propre liste du produit, ou un handle direct) — jamais le .values global. Deux pièges Liquid qui vous épargnent un après-midi : (1) un for sur une liste de références tronque silencieusement à 50 — les bundles de Combora n'y arrivent jamais (le plus grand plafond est 50 entrées au total), mais n'itérez pas les collections d'autrui en supposant que vous voyez tout ; (2) les champs optionnels (label, badge_label, cta_label) arrivent souvent vides — protégez-vous avec != blank comme ci-dessus.

22.7 Le lire depuis la Storefront API (localisé)

query BundleByHandle @inContext(language: FR) {
  metaobject(handle: { type: "combora_bundle", handle: "combora-bundle-{id}" }) {
    title:       field(key: "title")       { value }
    badge_label: field(key: "badge_label") { value }
    components:  field(key: "components") {
      references(first: 25) {
        nodes { ... on Metaobject {
          label:    field(key: "label")    { value }
          quantity: field(key: "quantity") { value }
        } }
      }
    }
  }
}

@inContext renvoie les traductions amorcées par l'application ; tout ce qui n'est pas traduit retombe automatiquement sur la langue de base.

22.8 Ce que vous pouvez construire avec cela

• Une interface de bundle entièrement personnalisée dans le thème, sans les blocs de Combora, en lisant le titre, le badge, les composants et l'économie depuis le metaobject.
• Une page de campagne : une page qui liste les bundles actifs depuis combora.index et affiche chacun par handle.
• Headless / Hydrogen : la même lecture via la Storefront API avec localisation par marché.
• Intégrations (flux, applications de recommandation) : le manifest déclare la version du contrat et où tout se trouve.

22.9 Règles pour le développeur

• Le prix appartient à la Function. Les champs du metaobject sont pour l'affichage : n'additionnez pas le discount_value d'un combo et ne recalculez pas les prix dans le thème — le paiement fait autorité.
• Uniquement additif : de nouveaux champs peuvent apparaître ; les existants ne changent pas. Écrivez des lectures qui tolèrent les champs inconnus.
• Combos : regroupez les enfants par position divisée par 1000 (chaque sous-offre occupe une bande de 1000) ou par config.of[].index — jamais par role, qui peut se répéter.
• Style : si vous construisez votre propre interface, ignorez style et écrivez votre CSS. Si au contraire vous voulez respecter le design que le commerçant a choisi dans l'application, copiez style.vars dans l'attribut style de votre racine et style.mode_class comme classe ; le préréglage Sans style de l'atelier existe exactement pour le cas inverse (balisage propre, votre CSS, avec .combora-w et les variables --combora-* comme points d'ancrage).
• Privé ≠ contrat : les metafields $app:runtime, $app:fnvars et $app:validation de la remise sont internes aux Functions, n'ont aucun accès storefront, et leur forme peut changer sans préavis. Ne construisez rien dessus.
• Multi-devises (Shopify Markets) : chaque montant du contrat — config.price, threshold, fixed_amount.amount, box_price — est toujours dans la devise de la boutique, en unités mineures. Si votre boutique vend en plusieurs devises, convertissez à l'affichage (en Liquid, multipliez par cart.currency.rate ; en JS, par Shopify.currency.rate) avant de formater ; afficher le nombre brut avec la devise de présentation de l'acheteur montre un prix erroné. La vraie remise au paiement est calculée par l'application et est toujours correcte — cette règle ne concerne que ce qu'affiche VOTRE widget.
• N'écrivez pas dans l'espace de noms combora. Shopify vous donne un accès en écriture dessus (c'est votre boutique), mais l'application le régénère à chaque publication et une révision nocturne restaure les champs qui gouvernent le forfait. Ce qui est à vous va dans votre propre espace de noms.
• Cette annexe est la référence complète du contrat pour les développeurs externes. S'il manque quelque chose et que vous en avez besoin, écrivez-nous via le chat de l'application ou à l'assistance et nous le documenterons.

23Annexe développeur : un widget par type, en Liquid

L'annexe précédente décrit ce que contient le contrat ; celle-ci montre comment afficher chaque type de bundle avec lui. Tout le code ci-dessous ne lit que le contrat public — aucune API de l'application, aucun des blocs propres à Combora — vous pouvez donc le coller dans un snippet ou dans un bloc Liquid personnalisé sur le modèle de produit et adapter le balisage librement. Trois règles s'appliquent à tout ce qui figure sur cette page :

• Le prix appartient à la Function. Tout ce qui suit n'est que de l'affichage ; le montant réellement facturé est calculé au paiement par la Shopify Function de Combora. Ne recalculez jamais un total pour le présenter comme le prix.
• Les montants sont en unités mineures, dans la devise de la boutique. Multipliez par cart.currency.rate avant de formater, sans quoi un acheteur qui navigue dans une autre devise voit un nombre erroné.
• Les champs optionnels sont souvent vides. Protégez-vous avec != blank — y compris le nom du composant après ses replis (voir 22.6).

23.1 Le squelette dans lequel chaque exemple s'insère

Une carte par bundle du produit courant, avec le titre, le badge et l'économie telle que le bundle l'exprime (discount_value en points de base ou en unités mineures). Chaque type affiche ensuite son propre corps à l'intérieur du case :

{%- liquid
  assign bundles = product.metafields.combora.bundles.value
  assign rate = cart.currency.rate | default: 1
-%}

{%- if bundles != blank -%}
  {%- for bundle in bundles -%}
    {%- liquid
      assign type = bundle.bundle_type.value
      assign dv = bundle.discount_value.value
      assign cfg = bundle.config.value
    -%}
    <article class="cx__card">
      <h3>{{ bundle.title.value | escape }}</h3>
      {%- if bundle.badge_label.value != blank -%}
        <span class="cx__badge">{{ bundle.badge_label.value | escape }}</span>
      {%- endif -%}

      {%- comment -%} L'économie, telle que ce bundle l'exprime {%- endcomment -%}
      {%- if dv.kind == 'percentage' -%}
        <p>Économisez {{ dv.bps | divided_by: 100 }}%</p>
      {%- elsif dv.kind == 'fixed_amount' -%}
        <p>Économisez {{ dv.amount | times: rate | money }}</p>
      {%- endif -%}

      {%- case type -%}
        {%- comment -%} un bloc par type — les sections 23.2 à 23.7 vont ici {%- endcomment -%}
      {%- endcase -%}
    </article>
  {%- endfor -%}
{%- endif -%}

23.2 Bundle fixe

Listez les enfants role == 'component' avec la chaîne de repli du nom, affichez le prix du bundle quand celui-ci utilise le mode prix (config.price, unités mineures), et liez vers le produit parent achetable :

{%- when 'fixed' -%}
  <ul>
    {%- for c in bundle.components.value -%}
      {%- if c.role.value == 'component' -%}
        {%- liquid
          assign name = c.label.value
          if name == blank
            assign name = c.variant.value.title
          endif
          if name == blank or name == 'Default Title'
            assign name = c.variant.value.product.title
          endif
        -%}
        {%- if name != blank -%}
          <li>{{ c.quantity.value }}× {{ name | escape }}</li>
        {%- endif -%}
      {%- endif -%}
    {%- endfor -%}
  </ul>
  {%- if cfg.price -%}
    <p class="cx__price">{{ cfg.price | times: rate | money }}</p>
  {%- endif -%}
  {%- if bundle.product.value != blank -%}
    <a href="{{ bundle.product.value.url }}">Acheter ce bundle</a>
  {%- endif -%}

Un bundle fixe en mode prix porte config.price et pas de discount_value ; en mode remise, c'est l'inverse — la ligne d'économie du squelette couvre déjà ce second cas.

Sur un produit à variante unique, le titre de variante est le libellé générique de Shopify «Default Title» : la chaîne de repli l'ignore et utilise le titre du produit (c'est le rôle de la condition supplémentaire).

23.3 Remise sur volume

L'échelle de paliers vit dans tiers (ordonnés par position), chaque palier avec ses propres min_qty et discount_value :

{%- when 'volume' -%}
  <table>
    {%- for t in bundle.tiers.value -%}
      {%- assign tv = t.discount_value.value -%}
      <tr>
        <td>Achetez-en {{ t.min_qty.value }}+</td>
        <td>
          {%- if tv.kind == 'percentage' -%}
            {{ tv.bps | divided_by: 100 }}% de remise
          {%- else -%}
            {{ tv.amount | times: rate | money }} de remise
          {%- endif -%}
        </td>
      </tr>
    {%- endfor -%}
  </table>

23.4 Achetez X, obtenez Y

La règle tient en deux scalaires dans config ; un pourcentage à 100% (bps == 10000) signifie que les articles de récompense sont gratuits :

{%- when 'bogo' -%}
  <p>Achetez-en {{ cfg.buy_qty }}, obtenez-en {{ cfg.get_qty }}
    {%- if dv.kind == 'percentage' and dv.bps == 10000 %} gratuits{% else %} remisés{% endif -%}.</p>

23.5 Mix & match et composez votre box

Les deux sont des offres « atteignez une quantité » : le mix lit le min_items du metaobject, la box lit config.slots (et config.box_price quand la box facture un prix fermé). Le réservoir éligible se trouve dans config.eligible (voir 22.4) :

{%- when 'mix_and_match' -%}
  <p>Choisissez-en {{ bundle.min_items.value }} ou plus dans la sélection.</p>
{%- when 'build_a_box' -%}
  <p>Remplissez une box de {{ cfg.slots }}.
    {%- if cfg.box_price %} Prix de la box {{ cfg.box_price | times: rate | money }}.{% endif -%}</p>

23.6 Compléments (FBT)

Les composants portent des rôles : l'anchor est le produit principal, les enfants suggestion sont les articles complémentaires :

{%- when 'fbt' -%}
  <ul>
    {%- for c in bundle.components.value -%}
      {%- if c.role.value == 'suggestion' or c.role.value == 'anchor' -%}
        <li>
          {{ c.variant.value.product.title | default: c.label.value | escape }}
          {%- if c.role.value == 'anchor' %} <em>(cet article)</em>{% endif -%}
        </li>
      {%- endif -%}
    {%- endfor -%}
  </ul>

23.7 Combo

Un combo imbrique des sous-offres. Regroupez ses enfants par position divisée par 1000 (chaque sous-offre occupe une bande de 1000) ou parcourez config.of[] — ne regroupez jamais par role, qui se répète d'une sous-offre à l'autre :

{%- when 'combo' -%}
  <ol>
    {%- for sub in cfg.of -%}
      <li>{{ sub.type | replace: '_', ' ' }}</li>
    {%- endfor -%}
  </ol>

23.8 Offres de cadeau à l'échelle de la boutique, sur n'importe quelle page

Les cadeaux annoncés sur toutes les pages produit vivent sur un metafield de boutique, et le Liquid du thème ne résout pas une liste de metaobjects au niveau de la boutique (22.1). Lisez plutôt l'index JSON et résolvez chaque bundle par handle :

{%- assign index = shop.metafields.combora.index.value -%}
{%- if index != blank -%}
  {%- for entry in index.bundles -%}
    {%- if entry.all_pdp and entry.status == 'active' -%}
      {%- assign gift = metaobjects['combora_bundle'][entry.handle] -%}
      {%- if gift != blank -%}
        <aside class="cx__gift">
          <strong>{{ gift.title.value | escape }}</strong>
          {%- assign gcfg = gift.config.value -%}
          {%- if gcfg.threshold -%}
            <span>Dépensez {{ gcfg.threshold | times: rate | money }} pour le débloquer.</span>
          {%- endif -%}
        </aside>
      {%- endif -%}
    {%- endif -%}
  {%- endfor -%}
{%- endif -%}

23.9 Le snippet complet

Tout ce qui précède, assemblé dans un seul fichier fonctionnel — le squelette, les six corps de type, les cadeaux à l'échelle de la boutique et un CSS minimal pour que ce soit lisible d'emblée : téléchargez combora-custom-bundle.liquid. Enregistrez-le comme snippets/combora-custom-bundle.liquid dans votre thème et affichez-le depuis le modèle de produit avec {% render 'combora-custom-bundle', product: product %}. Le GWP n'est pas dans le case, à dessein : un cadeau s'annonce (23.8 ou les blocs propres à l'application) et est ajouté automatiquement par l'application — un widget de fiche produit n'a rien à en vendre.

24Historique de cette édition

Chaque parcours de ce manuel a été testé dans une boutique réelle. Voici la trace de quand il a été vérifié et ce qui a changé ensuite, pour que vous sachiez à quel point ce que vous lisez est à jour.

Les captures d'écran se trouvent dans app/combora/public/manual/img/ dans le dépôt : celles de l'interface de l'application sous img/<langue>/, un jeu par langue, et celles de la boutique et de l'admin Shopify à la racine, car elles suivent votre thème et votre admin plutôt que la langue de l'application. Elles sont reprises depuis la boutique de démonstration ; voir docs/manual/CAPTURAS.md pour l'état requis pour chacune.