Dépannage, FAQ et Guide de Comportement Attendu

Ce guide couvre trois catégories de questions concernant BundlesIQ :

1. Comportement attendu — Votre commande semble différente de ce que vous attendiez, mais BundlesIQ fonctionne correctement en fonction de votre mode de traitement. Commencez par Section 1 si votre commande "semble incorrecte" mais que le traitement a réussi.
2. Diagnostic d'erreur — Quelque chose s'est mal passé pendant le traitement. Consultez Section 2 pour la liste de contrôle et Section 3 pour la résolution détaillée des erreurs.
3. FAQ et procédures — Questions courantes sur le traitement, la tarification, l'inventaire et les tâches opérationnelles. Consultez Section 4 à Section 7.

1. Comprendre le Comportement Attendu par Mode de Traitement

BundlesIQ transforme les commandes différemment selon votre mode de traitement. Avant de dépanner, confirmez que ce que vous voyez n'est pas le comportement prévu de votre mode choisi.

1.1 Référence Rapide : Ce Que Fait Chaque Mode à Votre Commande

Dans les quatre modes, le total de la commande reste inchangé par rapport à ce que le client a payé lors du passage à la caisse.

Pour vérifier votre mode : Ouvrez le bundle dans BundlesIQ > Bundles et regardez le champ Mode de Traitement. S'il indique "Utiliser le mode par défaut du magasin", vérifiez BundlesIQ > Paramètres > Mode de Traitement par Défaut.

1.2 Pourquoi BundlesIQ a-t-il Retiré le Bundle de ma Commande ?

Réponse courte : Vous utilisez le mode opérationnel. Retirer l'article de ligne de bundle est le comportement correct et attendu.

En mode opérationnel, BundlesIQ règle la quantité du bundle (SKU fantôme) à zéro et ajoute les SKUs de composants individuels avec leurs prix alloués. Le total de la commande reste inchangé. Cela est conçu pour les entrepôts, distributeurs et 3PL qui nécessitent une précision stricte au niveau des SKU — aucune abstraction de bundle laissée derrière.

Exemple — avant le traitement :

Bundle d'Essentiels d'Été (x1)    99,00 $

Après le traitement en mode opérationnel :

Lunettes de soleil (x1)                  41,25 $
Serviette de plage (x1)                 33,00 $
Crème solaire (x1)                       24,75 $
Total                                    99,00 $

La ligne de bundle a disparu. Seuls les vrais SKUs réalisables restent.

Si vous ne voulez pas que le bundle soit retiré, passez à l'un de ces modes :

• Mode hybride — Le bundle reste sur la commande à 0 $, les composants sont ajoutés avec des prix alloués. Bon pour B2B et gros.
• Mode reporting — Le bundle reste à son prix d'origine, les composants sont ajoutés à 0 $. Bon pour DTC et reporting de revenus propre.
• Mode Parent-Uni (BOM) — Le bundle reste à son prix d'origine, aucune ligne de composant n'est ajoutée. Bon pour les commandes sur mesure et les workflows de kitting.

Consultez Modes de Traitement Expliqués pour une comparaison complète.

Les changements de mode s'appliquent uniquement aux nouvelles commandes. Les commandes précédemment traitées ne sont pas modifiées rétroactivement. Consultez Section 1.7.

1.3 Pourquoi Mes Composants Sont-ils Affichés à 0 $ ?

Réponse courte : Vous utilisez le mode reporting. Les composants à 0 $ est le comportement correct et attendu.

En mode reporting, l'article de ligne de bundle conserve son prix d'origine (99,00 $ dans l'exemple), et les composants individuels sont ajoutés à 0,00 $ chacun. Cela maintient les revenus attribués au SKU de bundle, ce qui est idéal pour les marques DTC qui souhaitent des analyses Shopify propres et des vues de commande conviviales pour les clients.

Exemple — après le traitement en mode reporting :

Bundle d'Essentiels d'Été (x1)    99,00 $
Lunettes de soleil (x1)                   0,00 $
Serviette de plage (x1)                  0,00 $
Crème solaire (x1)                        0,00 $
Total                                    99,00 $

Si vous avez besoin de lignes de composants tarifées, passez au mode hybride ou mode opérationnel.

Remarque 3PL : Certains 3PL s'attendent à ce que tous les articles de ligne aient des prix pour les déclarations douanières. Si votre 3PL signale des problèmes avec des lignes de composants à 0 $, envisagez plutôt le mode hybride.

1.4 Pourquoi le Bundle Est-il Affiché à 0 $ sur la Commande ?

Réponse courte : Vous utilisez le mode hybride. Le bundle à 0 $ est le comportement correct et attendu.

En mode hybride, l'article de ligne de bundle est réglé à 0,00 $ et les articles de ligne de composants portent les prix alloués. Cela préserve à la fois ce qui a été acheté (la ligne de bundle) et ce qui doit être exécuté (les composants avec des prix), ce qui le rend idéal pour B2B et gros.

Exemple — après le traitement en mode hybride :

Bundle d'Essentiels d'Été (x1)     0,00 $
Lunettes de soleil (x1)                  41,25 $
Serviette de plage (x1)                 33,00 $
Crème solaire (x1)                       24,75 $
Total                                    99,00 $

Si vous voulez que le bundle conserve son prix d'origine, passez au mode reporting ou mode Parent-Uni (BOM).

1.5 Pourquoi Aucune Ligne de Composant N'a Été Ajoutée à Ma Commande ?

Réponse courte : Vous utilisez très probablement le mode Parent-Uni (BOM). Aucune ligne de composant sur la commande est le comportement correct et attendu.

En mode Parent-Uni, le bundle reste sur la commande exactement comme placé — aucune ligne d'article n'est ajoutée, aucun prix n'est changé. BundlesIQ gère l'inventaire des composants en arrière-plan en réservant, consommant et réapprovisionnant automatiquement le stock des composants.

Exemple — après le traitement en mode Parent-Uni :

Bundle d'Essentiels d'Été (x1)    99,00 $
Total                            99,00 $

(Aucune ligne d'article de composant sur la commande.
 L'inventaire des composants est réservé, consommé et réapprovisionné en arrière-plan.)

Comment vérifier que le traitement a réussi :

1. Vérifiez le tableau de bord de santé BundlesIQ — la commande doit afficher le statut Traité
2. Vérifiez le tag de commande BIQ_READY dans l'Admin Shopify
3. Vérifiez l'inventaire des produits composants — les quantités réservées devraient avoir augmenté

Si vous vous attendiez à ce que des lignes de composants apparaissent, vérifiez :

• Votre mode de traitement n'est pas réglé sur Parent-Uni (vérifiez à la fois le bundle et le mode par défaut du magasin)
• Si le mode est correct mais que les composants n'apparaissent toujours pas, consultez Section 2.1 pour le diagnostic des échecs de traitement

1.6 Que Voit le Client Après le Passage à la Caisse ?

L'expérience de passage à la caisse du client est identique dans les quatre modes — ils achètent le produit bundle à son prix affiché. La transformation se produit après le passage à la caisse, donc le timing est important :

Insight clé : L'email de confirmation de commande montre presque toujours la commande avant transformation car Shopify envoie l'email immédiatement après la création de la commande, avant que BundlesIQ ne reçoive le webhook et le traite.

Si la clarté de la commande côté client est importante, utilisez le mode reporting ou le mode Parent-Uni — ces modes préservent la vue de commande la plus familière pour le client, car le nom et le prix du bundle restent visibles même après transformation.

1.7 J'ai Changé Mon Mode de Traitement mais les Anciennes Commandes N'ont Pas Changé

C'est attendu. Les changements de mode de traitement s'appliquent uniquement aux nouvelles commandes. Les commandes précédemment traitées ne sont pas modifiées rétroactivement.

Pourquoi : BundlesIQ utilise l'API de modification de commande Shopify, qui crée des modifications suivies par audit. La re-transformation rétroactive des commandes générerait de nouvelles entrées de modification de commande, pourrait confondre la comptabilité et risquer l'intégrité des données pour des commandes qui pourraient déjà être exécutées ou partiellement exécutées.

Ce que vous pouvez faire :

• Pour les futures commandes : Le nouveau mode prend effet immédiatement pour les commandes passées après le changement
• Pour des commandes passées spécifiques (commandes brouillon uniquement) : Utilisez l'outil Revert & Reprocess pour re-transformer des commandes brouillon individuelles sous le nouveau mode
• Pour les commandes exécutées : Celles-ci ne peuvent pas être re-transformées. Ajustez le reporting manuellement si nécessaire
• Pour les commandes régulières non exécutées : Celles-ci ne peuvent pas être annulées (limitation de l'API de modification de commande Shopify), mais vous pouvez les re-traiter si la transformation d'origine a échoué

2. Diagnostiquer les Échecs de Traitement

2.1 Le Bundle N'a Pas Été Traité / Les Composants N'Ont Pas Apparu

Symptômes : Vous avez passé une commande contenant un produit bundle, mais la commande affiche toujours uniquement le SKU fantôme sans lignes d'articles de composants.

Mode Parent-Uni (BOM) : Si votre bundle utilise le mode Parent-Uni, c'est un comportement attendu. En mode Parent-Uni, aucune ligne d'article de composant n'est ajoutée à la commande. La ligne de bundle reste telle quelle et l'inventaire des composants est géré en arrière-plan. Vérifiez le tableau de bord de santé BundlesIQ pour confirmer que la commande a été traitée avec succès et vérifiez que les quantités réservées des composants ont augmenté. Consultez Section 1.5.

Vérifiez ceci dans l'ordre :

1. Le bundle est-il Actif ?

   • Ouvrez le bundle dans BundlesIQ > Bundles et vérifiez que le statut est Actif (pas Brouillon, Inactif ou Archivé)

2. Le traitement des commandes est-il activé ?

   • Allez dans BundlesIQ > Paramètres et vérifiez que Traiter les commandes est activé (ou Traiter les commandes brouillon si c'était une commande brouillon)

3. Le périmètre de traitement inclut-il cette commande ?

   • Si votre périmètre de traitement est réglé sur "Uniquement étiqueté", vérifiez que la commande a la balise requise
   • Si vous avez configuré des balises d'exclusion, vérifiez que la commande n'a pas de balise exclue

4. Le webhook a-t-il été reçu ?

   • Vérifiez le tableau de bord de santé BundlesIQ pour la commande. Si la commande n'apparaît pas du tout, Shopify n'a peut-être pas livré le webhook
   • Dans l'Admin Shopify, allez dans Paramètres > Notifications > Webhooks et vérifiez les livraisons échouées

   

5. Y avait-il une erreur de traitement ?

   • Vérifiez le tableau de bord de santé pour un statut Échoué sur la commande
   • Regardez le message d'erreur pour des détails (par exemple, variante de composant manquante, erreur API)

6. La commande a-t-elle déjà été exécutée ?

   • BundlesIQ ne traite que les commandes qui n'ont pas été exécutées. Si le statut de fulfillment de la commande n'est pas "non exécutée", le traitement est ignoré

7. La commande a-t-elle déjà été traitée ?

   • BundlesIQ est idempotent — il vérifie les métadonnées de transformation existantes avant de traiter. Si la commande a déjà été transformée, elle ne sera pas traitée à nouveau. Vérifiez le champ métadonnées de la commande bundles_iq.transformation_audit

8. Êtes-vous en mode Parent-Uni sans vous en rendre compte ?

   • Si le mode par défaut de votre magasin ou le remplacement au niveau du bundle est réglé sur Parent-Uni, la commande a été traitée mais aucune ligne de composant n'a été ajoutée — c'est par conception. Consultez Section 1.5

Si rien de tout cela ne s'applique, contactez le support avec le numéro de commande et une capture d'écran de votre tableau de bord de santé BundlesIQ.

Vous pouvez soumettre un ticket de support directement depuis la page de détail de traitement de la commande :

Les tickets de support incluent une conversation de chat en direct avec l'équipe Zapstra :

2.2 Référence Complète des Codes d'Erreur

Lorsque le traitement échoue, BundlesIQ enregistre un code d'erreur sur le tableau de bord de santé. Voici la référence complète de tous les codes d'erreur, regroupés par catégorie.

Erreurs d'Authentification

Erreurs de l'API Shopify

Erreurs de Commande Brouillon

Erreurs de Tarification

Erreurs de Produit et de Variante

Erreurs de Validation

Erreurs d'Entitlement et de Traitement

Erreurs Système

Erreurs BOM (Parent-Uni)

Ces erreurs s'appliquent uniquement aux bundles utilisant le mode Parent-Uni (BOM) :

2.3 Comprendre les Éléments d'Attention

Les éléments d'attention apparaissent sur le tableau de bord de santé pour signaler les commandes qui nécessitent une révision. Ils diffèrent des erreurs — la commande peut toujours avoir été traitée avec succès, mais quelque chose d'inhabituel a été détecté.

2.4 Comprendre les Indicateurs de Transformation

Les indicateurs de transformation sont des marqueurs d'information ajoutés aux commandes traitées pour expliquer les décisions de tarification. Ils apparaissent sur le tableau de bord de santé sous les détails de traitement de la commande.

Les indicateurs ne signifient pas nécessairement qu'il y a un problème. De nombreux indicateurs sont informatifs — par exemple, ORDER_LEVEL_PROMO_ROUNDING_VARIANCE signifie simplement que BundlesIQ a ajouté une ligne de réconciliation pour gérer une différence d'arrondi de 1 à 2 cents, ce qui est normal.

3. Plongées Profondes dans les Erreurs Spécifiques

3.1 Variance de Prix Critique

Code d'erreur : PRICE_VARIANCE_CRITICAL

Symptôme : La commande échoue au traitement avec une erreur de "variance de prix critique", ou le tableau de bord de santé affiche un élément d'attention price_variance_critical.

Ce que cela signifie : BundlesIQ a détecté que la somme des prix alloués des composants diffère considérablement du prix d'origine du bundle. Ce contrôle de sécurité empêche les commandes d'être transformées avec des totaux incorrects.

Causes courantes :

1. Le prix du composant a changé dans Shopify après la configuration du bundle

   • Si le prix Shopify d'un composant a augmenté depuis que vous avez configuré le bundle, BundlesIQ ne peut pas augmenter le prix de l'article de ligne sur les commandes finalisées (limitation de l'API de modification de commande Shopify)
   • L'écart entre l'allocation attendue et le prix réellement atteignable crée une variance

2. Interaction avec un code de remise

   • Un code de remise appliqué par le client peut créer une allocation qui entre en conflit avec la stratégie de tarification du bundle
   • Les remises en pourcentage sur les bundles avec des prix de composants en dollars peuvent créer des cas limites

3. Arrondi de devise sur les commandes internationales

   • Les commandes multi-devises peuvent produire des différences d'arrondi qui dépassent le seuil de variance

Résolution :

1. Ouvrez la commande dans le tableau de bord de santé et vérifiez les détails de tarification
2. Vérifiez le prix actuel de chaque composant dans Shopify par rapport à l'allocation configurée du bundle
3. Si le prix d'un composant a changé, mettez à jour la configuration de tarification du bundle pour refléter les prix actuels
4. Re-traitez la commande depuis le tableau de bord de santé après avoir corrigé la configuration
5. Si la variance est faible et attendue, contactez le support pour discuter de l'ajustement du seuil de variance

3.2 Édition Concurrente Détectée sur les Commandes Brouillon

Code d'erreur : DRAFT_CONCURRENT_EDIT

Symptôme : Une commande brouillon échoue au traitement avec une erreur "édition concurrente".

Ce que cela signifie : Pendant que BundlesIQ transformait la commande brouillon, un autre processus (une autre application, un utilisateur de l'Admin Shopify, ou un flux Shopify) a modifié la même commande brouillon. L'API de commande brouillon de Shopify utilise la concurrence optimiste — si le brouillon est modifié entre la lecture par BundlesIQ et l'écriture de la transformation, l'écriture échoue.

Causes courantes :

1. Une autre application modifiant les commandes brouillon — Les applications qui modifient les commandes brouillon (par exemple, applications de remise, applications fiscales) peuvent entrer en conflit
2. Édition manuelle pendant le traitement — Un membre du personnel a modifié la commande brouillon dans l'Admin Shopify pendant que BundlesIQ la traitait
3. Automatisation de flux Shopify — Un flux qui modifie les commandes brouillon peut se déclencher en même temps que BundlesIQ

Résolution :

1. Réessayez — Cliquez sur Réessayer dans le tableau de bord de santé. Dans la plupart des cas, l'édition concurrente était une condition de course ponctuelle et le réessai réussit
2. Si les réessais échouent encore — Identifiez l'autre processus qui édite la commande brouillon et coordonnez le timing. Vous devrez peut-être :
   • Désactiver temporairement d'autres applications de commande brouillon
   • Ajuster le timing du flux Shopify
   • S'assurer que le personnel ne modifie pas manuellement les commandes brouillon avant que BundlesIQ ne les traite

Cette erreur ne s'applique pas aux commandes régulières. Le traitement des commandes régulières utilise l'API de modification de commande, qui a des sémantiques de concurrence différentes.

3.3 Erreurs Spécifiques au BOM

Ces erreurs s'appliquent uniquement aux bundles utilisant le mode Parent-Uni (BOM). Elles concernent les opérations de réservation, de consommation et de libération d'inventaire.

BOM_INSUFFICIENT_AVAILABLE

Symptôme : Le traitement de la commande échoue car un composant n'a pas suffisamment d'inventaire disponible.

Cause : La quantité disponible du composant à l'emplacement d'inventaire cible est inférieure à ce que le bundle nécessite.

Résolution :

1. Vérifiez l'inventaire du composant dans l'Admin Shopify à l'emplacement pertinent
2. Réapprovisionnez le composant ou ajustez la stratégie d'emplacement
3. Si vous utilisez la stratégie "Emplacement de commande de fulfillment", vérifiez que la commande a un ordre de fulfillment assigné à un emplacement avec un stock suffisant
4. Re-traitez la commande après que l'inventaire soit disponible

BOM_RESERVATION_FAILED

Symptôme : L'appel API de réservation d'inventaire a échoué même si l'inventaire suffisant semble disponible.

Cause : Une erreur transitoire de l'API d'inventaire de Shopify, ou un autre processus a modifié l'inventaire entre la vérification de disponibilité et l'appel de réservation.

Résolution :

1. Réessayez depuis le tableau de bord de santé — cela résout généralement les problèmes d'API transitoires
2. Si cela persiste, vérifiez si une autre application de gestion d'inventaire entre en conflit
3. Vérifiez que l'emplacement d'inventaire est correctement configuré dans Shopify

BOM_CONSUMPTION_FAILED

Symptôme : Lorsque la commande a été exécutée, BundlesIQ n'a pas pu consommer (décrémenter) l'inventaire réservé.

Cause : La réservation peut avoir déjà été manuellement libérée ou consommée par un autre processus, ou une erreur de l'API Shopify s'est produite.

Résolution :

1. Vérifiez les niveaux d'inventaire du composant — si la réservation a déjà été consommée, aucune action n'est nécessaire
2. Si l'inventaire est incorrect, ajustez-le manuellement dans l'Admin Shopify
3. Vérifiez les journaux du tableau de bord de santé pour l'erreur API spécifique

BOM_RELEASE_FAILED

Symptôme : Lorsque la commande a été annulée, BundlesIQ n'a pas pu libérer l'inventaire réservé.

Cause : La réservation peut avoir déjà été consommée (si la commande a été exécutée avant l'annulation) ou libérée par un autre processus.

Résolution :

1. Vérifiez si l'inventaire a déjà été libéré — si les quantités disponibles semblent correctes, aucune action n'est nécessaire
2. Si l'inventaire est bloqué dans un état réservé, ajustez-le manuellement dans l'Admin Shopify
3. Contactez le support si cela se produit de manière répétée

BOM_LOCATION_NOT_FOUND

Symptôme : BundlesIQ ne peut pas déterminer quel emplacement d'inventaire utiliser pour la réservation.

Cause : Dépend de la stratégie d'emplacement :

• "Emplacement de commande de fulfillment" — La commande n'a pas d'ordre de fulfillment avec un emplacement assigné, ou l'emplacement assigné ne porte pas le composant
• "Emplacement unique" — L'emplacement configuré n'existe pas ou n'a pas le produit composant en stock

Résolution :

1. Vérifiez la stratégie d'emplacement dans BundlesIQ > Paramètres ou les paramètres de remplacement du bundle
2. Si vous utilisez l'emplacement de commande de fulfillment, vérifiez que la commande a un ordre de fulfillment assigné à un emplacement valide
3. Si vous utilisez un emplacement unique, vérifiez que l'emplacement configuré existe et a les produits composants en stock
4. Assurez-vous que les composants sont en stock à l'emplacement pertinent dans l'Admin Shopify

3.4 Erreurs de l'API Shopify

Codes d'erreur : SHOPIFY_THROTTLED, SHOPIFY_API_ERROR, SHOPIFY_TIMEOUT

Symptôme : Le traitement échoue avec une erreur liée à l'API Shopify.

Comment BundlesIQ gère les problèmes d'API Shopify :

• Limites de taux (SHOPIFY_THROTTLED) : BundlesIQ attend automatiquement et réessaie avec un délai exponentiel. Aucune action n'est nécessaire dans la plupart des cas. Pendant les événements de forte activité (ventes flash, importations en masse), vous pouvez voir un léger retard dans le traitement.
• Erreurs API (SHOPIFY_API_ERROR) : Celles-ci sont généralement transitoires. BundlesIQ réessaie automatiquement jusqu'au nombre maximum de tentatives configuré (par défaut : 1 réessai automatique).
• Timeouts (SHOPIFY_TIMEOUT) : L'API Shopify a mis trop de temps à répondre. BundlesIQ réessaie automatiquement.

Quand prendre des mesures :

• Si une erreur d'API Shopify persiste après des réessais automatiques, vérifiez Statut Shopify pour des problèmes de plateforme en cours
• Si la limitation de taux est fréquente, vérifiez si d'autres applications sur votre magasin consomment une quota API excessive
• Cliquez sur Réessayer dans le tableau de bord de santé pour déclencher manuellement un réessai après que le problème soit résolu

3.5 Erreurs d'Authentification

Codes d'erreur : AUTH_MISSING_CREDENTIALS, AUTH_MISSING_TOKEN, AUTH_INVALID_TOKEN, AUTH_PERMISSIONS_REVOKED

Symptôme : Le traitement échoue avec une erreur d'authentification. Toutes les commandes échouent, pas seulement des bundles spécifiques.

Causes courantes :

1. Les autorisations de l'application ont été révoquées — Quelqu'un a modifié les autorisations de l'application dans l'Admin Shopify
2. L'application a été désinstallée et réinstallée — Le jeton d'accès précédent a été invalidé
3. Rotation de jeton Shopify — Rare, mais Shopify peut faire tourner les jetons pendant les mises à jour de plateforme

Résolution :

1. Allez dans Admin Shopify > Paramètres > Applications et canaux de vente
2. Trouvez BundlesIQ et cliquez sur Gérer
3. Si des autorisations manquent, cliquez pour les réaccorder
4. Si le problème persiste, désinstallez et réinstallez BundlesIQ depuis l'App Store Shopify
5. Après la réinstallation, vérifiez que vos bundles et paramètres sont intacts (ils sont stockés côté serveur et se reconnecteront)

Toutes les commandes en file d'attente seront traitées une fois l'authentification rétablie. Aucune commande n'est perdue.

4. Dépannage de la Tarification et des Rapports

4.1 La Remise ou le Prix Semble Incorrect

Symptômes : Après le traitement du bundle, les prix des composants sur la commande ne correspondent pas à ce que vous attendiez.

Vérifiez ceci dans l'ordre :

1. Vérifiez votre stratégie de tarification

   • Ouvrez le bundle dans BundlesIQ et vérifiez le mode de tarification (dirigé par le bundle ou dirigé par le composant) et la stratégie
   • Vérifiez l'aperçu des prix pour voir l'allocation attendue

2. Vérifiez les avertissements de tarification (indicateurs de transformation)

   • Dans le tableau de bord de santé BundlesIQ, recherchez des indicateurs sur la commande :

   

   • BUNDLE_EXCEEDS_COMPONENTS — Le prix du bundle est supérieur à la somme des prix de composants. Consultez Section 2.4
   • PRICE_INCREASE_NOT_POSSIBLE — Un composant n'a pas pu être réglé au prix cible car l'API de modification de commande ne permet pas d'augmentations de prix. Consultez Section 2.4
   • SPECIFIC_RETAIL_EXCEEDS_CONTEXTUAL — Le prix de détail configuré d'un composant dans BundlesIQ est supérieur à son prix Shopify actuel. Le prix Shopify est utilisé à la place
   • DOLLAR_DISCOUNT_EXCEEDS_RETAIL — Une remise en dollars est plus grande que le prix de détail du composant. La remise est limitée au prix de détail
   • ORDER_LEVEL_PROMO_ROUNDING_VARIANCE — Une petite différence d'arrondi a été détectée lors de la distribution d'une promotion au niveau de la commande. Une ligne de réconciliation a été ajoutée pour équilibrer le total

3. Vérifiez si un code de remise Shopify a été appliqué

   • Si le client a utilisé un code de remise lors du passage à la caisse, BundlesIQ le prend en compte dans l'allocation de prix
   • L'effet combiné de l'allocation du bundle + du code de remise peut produire des prix par composant qui semblent inattendus

4. Vérifiez la variance d'arrondi

   • De petites différences de 1 à 10 cents peuvent se produire en raison de l'arrondi lors de l'allocation des prix
   • L'absorbeur de variance de BundlesIQ corrige automatiquement ces différences, mais vous pouvez voir des pourcentages de remise légèrement différents sur les composants individuels

5. Vérifiez le prix actuel du composant dans Shopify

   • BundlesIQ utilise le prix actuel du composant dans Shopify (prix contextuel) lors du calcul des remises
   • Si le prix d'un composant a changé après la configuration du bundle, l'allocation peut différer de l'aperçu

4.2 Les Rapports Ne Correspondent Pas à Ce Que J'Attends

Symptômes : Les analyses Shopify ou vos outils de reporting montrent une attribution de revenus inattendue, des classements de best-sellers ou des données de ventes après la mise en œuvre de BundlesIQ.

Comprenez la cause profonde :

L'attribution des revenus dépend entièrement de votre mode de traitement :

Si vous voulez des revenus sur le SKU de bundle : Utilisez le mode reporting ou le mode Parent-Uni (BOM)

Si vous voulez des revenus sur les SKUs de composants : Utilisez le mode hybride ou mode opérationnel

Si vous avez déjà traité des commandes dans le mauvais mode :

• Changez votre mode de traitement à l'avenir (nouvelles commandes uniquement)
• Les commandes précédemment traitées ne sont pas modifiées rétroactivement
• Vous devrez peut-être réconcilier manuellement les données historiques dans vos outils de reporting

Classements de best-sellers :

• Dans les modes Hybride et Opérationnel, les composants individuels peuvent apparaître comme les meilleurs vendeurs au lieu du bundle
• Dans les modes Reporting et Parent-Uni, le produit bundle apparaît dans les classements de best-sellers

Flux de canaux (Meta, TikTok, Google) :

• Certaines intégrations de canaux lisent les données de commande pour déterminer la performance des produits
• Dans les modes Hybride et Opérationnel, les analyses de canaux peuvent attribuer des ventes aux SKUs de composants
• Si l'attribution de canal est importante, envisagez le mode Reporting

5. Inventaire et Disponibilité

5.1 Le Bundle Est Affiché Comme Épuisé

Symptômes : Votre produit bundle est affiché comme "Épuisé" sur la vitrine, mais vous croyez que les composants ont de l'inventaire.

Vérifiez ceci dans l'ordre :

1. Vérifiez tous les niveaux d'inventaire des composants

   • La disponibilité du bundle est déterminée par le composant le moins disponible
   • Ouvrez chaque produit composant dans l'Admin Shopify et vérifiez son inventaire à l'emplacement pertinent
   • Même un composant à zéro rend l'ensemble du bundle indisponible

2. Vérifiez le bon emplacement

   • Si vous avez plusieurs emplacements Shopify, vérifiez l'inventaire à l'emplacement qui sert les commandes en ligne
   • Un composant peut avoir du stock à un emplacement mais pas à un autre

3. Vérifiez le paramètre de suivi d'inventaire du SKU fantôme

   • Si le suivi d'inventaire est activé sur le SKU fantôme, BundlesIQ règle sa quantité disponible en fonction des composants
   • Si le suivi d'inventaire est désactivé, le produit devrait toujours être affiché comme en stock — vérifiez d'autres raisons pour lesquelles il pourrait être caché (statut du produit, disponibilité du canal)

4. Vérifiez "Continuer à vendre lorsque épuisé"

   • Sur la variante du SKU fantôme : si cela est désactivé et que l'inventaire est à 0, Shopify affiche "Épuisé"
   • Si vous souhaitez autoriser les achats même lorsque la disponibilité calculée est à 0, activez ce paramètre (mais soyez conscient du risque de survente)

5. Vérifiez si la synchronisation d'inventaire est activée

   • Dans BundlesIQ > Paramètres, vérifiez que Synchroniser l'inventaire du bundle est activé
   • Sur le bundle spécifique, vérifiez que la synchronisation d'inventaire n'est pas désactivée au niveau du bundle

6. Calculez la disponibilité manuellement

   • Pour chaque composant : divisez la quantité disponible par la quantité par bundle
   • Le résultat minimum est la disponibilité du bundle
   • Comparez avec l'inventaire actuel du SKU fantôme dans Shopify

7. Mode Parent-Uni (BOM) : vérifiez les quantités réservées

   • Si vous utilisez le mode Parent-Uni, l'inventaire des composants réservés réduit la quantité disponible
   • Si de nombreuses commandes ont réservé mais pas encore consommé les composants, la quantité disponible peut être inférieure à ce que vous attendiez
   • Vérifiez la répartition réservée vs. disponible du composant dans l'Admin Shopify

5.2 Parent-Uni : L'Inventaire des Composants N'est Pas Réservé

Symptômes : Vous avez passé une commande avec un bundle Parent-Uni, mais les quantités réservées de l'inventaire des composants n'ont pas changé.

Vérifiez ceci dans l'ordre :

1. La commande a-t-elle été traitée ?

   • Vérifiez le tableau de bord de santé BundlesIQ pour le statut de la commande
   • Si la commande n'est pas répertoriée, le webhook peut ne pas avoir été reçu

2. Vérifiez le paramètre de timing de réservation

   • Si le timing de réservation est réglé sur orders/paid, l'inventaire n'est réservé qu'après confirmation du paiement
   • Si la commande est impayée, passez à orders/create pour réserver immédiatement, ou attendez le paiement

3. Vérifiez la stratégie d'emplacement

   • Si réglé sur "Emplacement de commande de fulfillment", vérifiez que la commande a un ordre de fulfillment assigné à un emplacement avec de l'inventaire de composants
   • Si réglé sur "Emplacement unique", vérifiez que l'emplacement configuré a un stock suffisant de composants

4. Vérifiez les niveaux d'inventaire des composants

   • Si un composant a zéro disponible à l'emplacement cible, la réservation peut échouer
   • Vérifiez le tableau de bord de santé pour des détails d'erreur — consultez Section 3.3 pour la résolution des erreurs spécifiques au BOM

6. Procédures et Conseils Opérationnels

6.1 Réessayer vs. Re-traiter : Lequel Dois-je Utiliser ?

Les deux options sont disponibles sur le tableau de bord de santé, mais elles font des choses différentes :

Guide de décision :

• La commande a échoué avec SHOPIFY_THROTTLED, SHOPIFY_API_ERROR, ou SHOPIFY_TIMEOUT → Réessayer
• La commande a échoué avec DRAFT_CONCURRENT_EDIT → Réessayer (l'édition concurrente était probablement une condition de course ponctuelle)
• Vous avez changé la configuration du bundle (composants, tarification, mode de traitement) → Re-traiter
• La commande a un état de transformation obsolète ou corrompu → Re-traiter (mode forcé)
• La commande a échoué avec PRODUCT_NOT_FOUND ou VARIANT_NOT_FOUND et vous avez corrigé le produit → Re-traiter
• Vous n'êtes pas sûr → Commencez par Réessayer. Si cela échoue à nouveau avec la même erreur, enquêtez et ensuite Re-traiter après avoir corrigé le problème

Remarque sur le mode Parent-Uni (BOM) : Re-traiter une commande Parent-Uni libérera toutes les réservations d'inventaire existantes avant de relancer le pipeline. Si la commande a déjà été partiellement exécutée, certaines réservations peuvent avoir déjà été consommées — utilisez avec prudence.

6.2 Comment Savoir Si une Commande a Été Traité

Il existe plusieurs façons de confirmer si BundlesIQ a traité une commande :

1. Vérifiez les balises de commande dans l'Admin Shopify

   • BIQ_READY — La commande a été traitée avec succès
   • BIQ_PROCESSING — Le traitement est actuellement en cours
   • BIQ_ERROR — Le traitement a échoué (vérifiez le tableau de bord de santé pour des détails)
   • BIQ_REVERTED — Une commande brouillon a été rétablie à son état avant transformation

2. Vérifiez le champ métadonnées de la commande

   • Recherchez le champ métadonnées bundles_iq.transformation_audit sur la commande
   • Cela contient l'intégralité de l'enregistrement de transformation y compris les mappages de bundle, les allocations de prix et les indicateurs

3. Vérifiez le tableau de bord de santé BundlesIQ

   • Recherchez la commande par numéro ou ID
   • Le tableau de bord montre le statut de traitement, la chronologie, et toutes les erreurs ou éléments d'attention

4. Vérifiez les lignes de composants (uniquement en modes Hybride, Opérationnel et Reporting)

   • En mode Hybride : bundle à 0 $, composants avec prix
   • En mode Opérationnel : bundle retiré, seuls les composants restent
   • En mode Reporting : bundle au prix d'origine, composants à 0 $
   • En mode Parent-Uni : aucun changement visible sur la commande — utilisez le tableau de bord de santé ou la balise BIQ_READY à la place

6.3 Re-traiter et Revenir en Arrière sur les Commandes

BundlesIQ fournit des outils d'administration pour re-traiter les commandes échouées et revenir en arrière sur les transformations de commandes brouillon. Ces outils sont accessibles depuis la page de détail de commande/brouillon dans l'Admin Shopify via le menu d'action Outils de Bundle.

Re-traiter (Commandes et Commandes Brouillon)

Re-traiter relance l'ensemble du pipeline de transformation de bundle pour une commande. Utilisez cela lorsque :

• Le traitement a échoué et que l'erreur a été résolue (par exemple, une variante manquante a été réajoutée)
• La configuration du bundle a été changée et vous souhaitez re-transformer une commande
• Un état de traitement obsolète doit être effacé

Consultez Section 6.1 pour des conseils sur quand réessayer vs. re-traiter.

Comment re-traiter :

1. Ouvrez la commande ou la commande brouillon dans l'Admin Shopify
2. Cliquez sur l'action Outils de Bundle (dans le menu "Plus d'actions")
3. Cliquez sur Re-traiter le Bundle
4. Si la commande a déjà été traitée avec succès, BundlesIQ vous avertira et proposera une option de Re-traitement Forcé

Ce qui se passe lors du re-traitement :

1. Les instances de bundle existantes dans BundlesIQ sont annulées et supprimées
2. Toutes les balises BIQ_* sont retirées de la commande (y compris BIQ_PROCESSING, BIQ_READY, BIQ_ERROR, et BIQ_REVERTED)
3. Si le champ métadonnées du bundle existe déjà sur la commande, il est supprimé (mode forcé uniquement)
4. L'intégralité des données de commande est récupérée depuis Shopify et publiée pour traitement
5. Le webhook-worker détecte les bundles et les traite comme si la commande était nouvelle

Re-traitement Forcé est une escalade de sécurité. Cela supprime les instances traitées existantes et les métadonnées avant de relancer le pipeline. Utilisez-le uniquement lorsque vous êtes certain que la transformation précédente doit être remplacée.

Remarque sur le mode Parent-Uni (BOM) : Re-traiter une commande Parent-Uni libérera toutes les réservations d'inventaire existantes avant de relancer le pipeline. Si la commande a déjà été partiellement exécutée, certaines réservations peuvent avoir déjà été consommées — utilisez avec prudence et vérifiez les niveaux d'inventaire après le re-traitement.

Revenir en Arrière (Commandes Brouillon Uniquement)

Revenir en arrière annule une transformation de bundle sur une commande brouillon, la restaurant à son état avant BundlesIQ. Cela n'est disponible que pour les commandes brouillon — les commandes régulières ne peuvent pas être annulées car l'API de modification de commande ne prend pas en charge la suppression des lignes d'articles précédemment ajoutées.

Comment revenir en arrière :

1. Ouvrez la commande brouillon dans l'Admin Shopify
2. Cliquez sur l'action Outils de Bundle
3. Choisissez l'une des options :
   • Revenir Seulement — Supprime toutes les lignes de composants de bundle et restaure les lignes de SKU fantôme d'origine. La commande brouillon est laissée dans son état avant transformation et ne sera pas re-traitée (une balise BIQ_REVERTED est appliquée pour empêcher la re-transformation automatique)
   • Revenir & Re-traiter — Rétablit la commande brouillon et relance immédiatement l'ensemble du pipeline de traitement. Toutes les balises BIQ_* sont retirées et un nouveau traitement propre commence

Ce que fait le retour en arrière selon le mode de traitement :

La Balise BIQ_REVERTED

Lorsqu'une commande brouillon est rétablie (sans re-traitement), BundlesIQ applique la balise BIQ_REVERTED. Cette balise indique au webhook-worker d'ignorer la commande brouillon lorsque le webhook draft_orders/update se déclenche (que Shopify envoie en réponse à la mutation de retour). Sans cette balise, le worker transformerait immédiatement la commande brouillon.

• Revenir Seulement : la balise BIQ_REVERTED reste — empêche la re-transformation automatique
• Revenir & Re-traiter : toutes les balises BIQ_* sont retirées — la republication intentionnelle déclenche un nouveau traitement propre

7. Questions Fréquemment Posées

7.1 Combien de Temps Prend le Traitement ?

BundlesIQ traite les commandes de manière asynchrone après avoir reçu le webhook de Shopify :

Si la protection 3PL est activée, la commande est retenue jusqu'à ce que le traitement soit terminé, donc les variations de timing ne causent pas de problèmes de fulfillment.

7.2 Les Propriétés des Articles de Ligne se Transfèrent-elles aux Composants ?

BundlesIQ ne transfère actuellement pas les propriétés des articles de ligne (telles que les messages cadeaux, le texte de gravure ou les champs personnalisés) de l'article de ligne SKU fantôme aux articles de ligne de composants.

Solution de contournement : Si vous avez besoin de propriétés d'articles de ligne sur les composants, vous pouvez :

• Ajouter les propriétés manuellement après que BundlesIQ ait traité la commande
• Utiliser un flux Shopify pour copier les propriétés de la ligne d'origine aux lignes de composants
• Contacter le support pour discuter de votre cas d'utilisation spécifique

7.3 Les Clients Peuvent-ils Toujours Appliquer des Codes de Remise ?

Oui. Les clients peuvent appliquer des codes de remise Shopify lors du passage à la caisse comme d'habitude. BundlesIQ détecte toutes les remises appliquées et les prend en compte dans l'allocation des prix des composants pendant la transformation.

Comment cela fonctionne :

• Le code de remise est appliqué au SKU fantôme lors du passage à la caisse
• BundlesIQ détecte la remise et son type (pourcentage, montant fixe, BOGO, etc.)
• Pendant la transformation, BundlesIQ distribue à la fois la remise d'allocation du bundle et la remise de passage à la caisse entre les composants

Limitations :

• Les remises automatiques de Shopify fonctionnent de la même manière — BundlesIQ les prend en compte
• Le comportement d'empilement des remises est régi par les règles de Shopify (par exemple, une seule remise par commande, sauf si votre magasin prend en charge l'empilement)

7.4 BundlesIQ Fonctionne-t-il avec Shopify POS ?

Oui. BundlesIQ traite les commandes de tous les canaux Shopify, y compris POS. Lorsqu'une commande POS contient un SKU fantôme de bundle, elle est traitée de la même manière qu'une commande en ligne.

Remarque : BundlesIQ ne fournit pas d'interface utilisateur spécifique à POS. Le personnel utilisant POS doit ajouter le produit SKU fantôme à la vente ; BundlesIQ transforme la commande après sa création.

7.5 Que Se Passe-t-il Si Je Change Mon Mode de Traitement Après Avoir Traité des Commandes ?

Le changement de mode s'applique uniquement aux nouvelles commandes. Les commandes précédemment traitées ne sont pas modifiées rétroactivement. Consultez Section 1.7 pour des détails.

Remplacements par bundle : Vous pouvez définir différents modes de traitement par bundle. Cela signifie que vous pouvez exécuter le mode opérationnel pour vos bundles en gros et le mode reporting pour vos bundles DTC simultanément.

7.6 Pourquoi le Client Voit-il Quelque Chose de Différent sur Son Email de Confirmation de Commande ?

L'email de confirmation de commande est envoyé par Shopify immédiatement après la création de la commande — avant que BundlesIQ ne reçoive le webhook et traite la commande. Cela signifie que l'email montre la commande d'origine, avant transformation (juste le produit bundle au prix d'achat).

Après le traitement (généralement 2-15 secondes plus tard), la commande dans l'Admin Shopify montre la version transformée. Si le client vérifie sa page de statut de commande ou son historique de compte après que le traitement soit terminé, il voit la commande transformée.

Consultez Section 1.6 pour le décompte complet.

Astuce : Si vous souhaitez que la commande côté client corresponde le plus possible à l'email, utilisez le mode reporting ou le mode Parent-Uni — ces modes préservent le nom et le prix du bundle sur la commande, de sorte que la commande transformée ressemble beaucoup à l'email.

7.7 Commandes Multi-Bundles : À Quoi S'Attendre

Lorsqu'une seule commande contient plusieurs bundles, BundlesIQ traite tous les bundles dans une seule transformation :

• Tous les bundles sur la commande sont détectés lors du traitement initial du webhook
• Chaque bundle est transformé indépendamment selon son propre mode de traitement (si des remplacements par bundle sont définis)
• Les lignes de composants sont ajoutées pour chaque bundle — si deux bundles partagent une variante de composant, ces lignes de composants apparaissent séparément (une par bundle)
• Le temps de traitement augmente légèrement avec plusieurs bundles (5-15 secondes typiques)

Modes de traitement mixtes sur une commande :

Si un bundle est réglé sur le mode hybride et un autre sur le mode opérationnel, la transformation de chaque bundle suit ses propres règles de mode. La commande peut montrer un mélange de lignes de bundle à 0 $, de lignes de bundle retirées et de lignes de composants tarifées.

Astuce : Pour plus de simplicité, nous recommandons d'utiliser le même mode de traitement pour tous les bundles sur un magasin unique. Les modes mixtes sur une commande unique sont pris en charge mais peuvent créer des commandes qui semblent déroutantes.

7.8 Le Traitement Prend Plus de Temps Que Prévu

Symptômes : Les commandes ne sont pas transformées dans la fenêtre de 2-15 secondes attendue.

Causes possibles :

1. Volume élevé de webhooks — Pendant les événements de vente ou les importations de commandes en masse, le traitement des webhooks peut être mis en file d'attente
2. Limitation de l'API Shopify — Si votre magasin atteint les limites de taux de l'API Shopify, BundlesIQ attend et réessaie
3. Bundles complexes — Les bundles avec de nombreux composants ou plusieurs bundles sur une seule commande prennent plus de temps
4. Réessai en cours — Si le traitement initial a échoué, BundlesIQ peut attendre la période de refroidissement avant de réessayer

Que faire :

• Vérifiez le tableau de bord de santé pour le statut de la commande
• Si la commande affiche "En attente" ou "Traitement", attendez quelques minutes
• Si la commande affiche "Échoué", vérifiez le message d'erreur et résolvez le problème
• Si la protection 3PL est activée, la commande reste retenue jusqu'à ce que le traitement soit terminé — aucun risque de fulfillment

7.9 Questions Courantes de la Semaine de Lancement

Si vous venez de mettre en ligne BundlesIQ, voici les situations les plus courantes au cours de la première semaine :

"Mon 3PL a importé des commandes avant que BundlesIQ ne les traite"

Si votre 3PL tire des commandes immédiatement après leur création (avant la fenêtre de traitement de 2-15 secondes de BundlesIQ), le 3PL peut avoir importé la commande avant transformation.

Solution : Activez la protection 3PL (retenue de fulfillment) dans BundlesIQ > Paramètres. Cela place une retenue de fulfillment sur les commandes jusqu'à ce que le traitement soit terminé, empêchant l'importation prématurée par le 3PL. La retenue est automatiquement levée après une transformation réussie.

"Mon entrepôt est confus par les lignes de composants à 0 $"

Si vous utilisez le mode reporting, les lignes de composants apparaissent à 0 $. Certains membres du personnel d'entrepôt ou 3PL interprètent cela comme des "articles gratuits" ou sont confus par les lignes à zéro dollar.

Solutions :

• Passez au mode opérationnel si l'entrepôt a uniquement besoin de vrais SKUs et de prix (aucune référence de bundle nécessaire)
• Passez au mode hybride si vous souhaitez que la référence de bundle soit visible mais que les composants soient tarifés
• Formez le personnel d'entrepôt à ce que les lignes à 0 $ en mode reporting sont des articles uniquement pour fulfillment — la ligne de bundle porte le prix total
• Utilisez la fonctionnalité d'en-tête de bundle dans les Options de Rédacteur pour ajouter des étiquettes de regroupement

"Certaines commandes ont été traitées mais d'autres ne l'ont pas été"

Vérifiez ces causes courantes de la semaine de lancement :

1. Portée de traitement : Est-elle réglée sur "Toutes les commandes" ou "Uniquement étiquetées" ? Si étiquetée uniquement, vérifiez les étiquettes
2. Statut du bundle : Tous les bundles sont-ils réglés sur Actif ? Les bundles brouillons ne sont pas traités
3. Timing des commandes : Les commandes passées avant que BundlesIQ ne soit installé/activé ne sont pas traitées rétroactivement
4. Mismatch de SKU fantôme : Vérifiez que l'ID de variante du SKU fantôme dans le bundle correspond au produit variant Shopify réel

"J'ai lancé avec le mauvais mode de traitement"

Pas de problème — changez le mode dans BundlesIQ > Paramètres (ou remplacement par bundle). Le nouveau mode s'applique immédiatement à toutes les nouvelles commandes. Les commandes précédemment traitées ne sont pas affectées. Si vous devez re-transformer des commandes brouillon spécifiques, utilisez Revert & Reprocess.

8. Pages Connexes

• Commencer
• Modes de Traitement Expliqués
• À Quoi Ressemblent les Commandes dans Chaque Mode
• Configuration de la Stratégie de Tarification
• Règles d'Inventaire
• Liste de Vérification de Mise en Ligne
• Guide d'Intégration 3PL
• Aperçu des Paramètres Globaux