Shopify API 2026-04 : reprendre un ajustement de stock sans compter les pièces deux fois

Votre entrepôt confirme une réception de cinq pièces. Le connecteur envoie l’ajustement à Shopify, puis attend jusqu’au timeout. Le mouvement peut avoir été enregistré, mais votre application n’a aucune réponse exploitable. Une relance avec une nouvelle clé risque d’ajouter cinq pièces supplémentaires ; une absence de relance laisse la réception sans confirmation. Le support doit décider sans confondre panne de transport et échec d’écriture.

Depuis l’API GraphQL Admin 2026-04, Shopify exige une clé d’idempotence pour inventoryAdjustQuantities, ainsi qu’un champ changeFromQuantity explicitement renseigné. Ces deux mécanismes répondent à des questions différentes : reconnaître la même opération et contrôler la quantité sur laquelle une nouvelle modification s’appuie. Les ajouter à la requête ne suffit pas si le connecteur les reconstruit différemment à chaque tentative.

En pratique, la reprise doit commencer par l’identité de la réception, puis retrouver la requête conservée et son issue. Vous pourrez distinguer les erreurs qui autorisent une tentative identique de celles qui imposent une nouvelle décision, avec sept situations à éprouver localement. La règle proposée bloque le rejeu tardif incertain au lieu de supposer que la protection fournisseur dure indéfiniment.

Notre prestation d’intégration API examine cette frontière entre mouvement métier et requête réseau. Pour un raccordement ERP ou WMS, le connecteur Shopify doit permettre de retrouver une réception, son ajustement et sa preuve de traitement. L’objectif est une reprise explicable à l’équipe logistique, au fournisseur du logiciel et au mainteneur du middleware.

Pour qui : un connecteur qui ajoute des mouvements de stock

Reconnaître une addition derrière le mot synchronisation

Le problème concerne les intégrations qui transmettent des écarts : réception fournisseur, correction d’inventaire autorisée ou mouvement validé dans un entrepôt. Un delta de cinq augmente une quantité ; il ne demande pas simplement de la remplacer par cinq. Si deux tentatives représentent la même réception, elles ne doivent pas devenir deux mouvements indépendants. L’identité de la réception existe donc avant l’appel, dans le logiciel qui l’a approuvée.

La référence de la mutation d’ajustement décrit cette modification incrémentale et ses autorisations, dont le scope write_inventory. Elle indique également l’obligation d’idempotence à partir de 2026-04. Le fournisseur du connecteur vérifie la version réellement appelée et les permissions de son application ; une requête compilée ne prouve ni son autorisation ni son résultat métier.

Séparer ce diagnostic des autres causes d’indisponibilité

Un produit non publié, un niveau d’inventaire inactif ou une quantité réservée peuvent expliquer une offre fermée sans qu’une réception ait été perdue. Ici, l’enquête part d’un mouvement déterminé et d’une réponse manquante. Le connecteur ne doit pas ajouter des unités pour rendre une fiche achetable. Il conserve le motif de l’opération initiale et recherche ce qui lui est arrivé.

Une synchronisation de valeurs absolues soulève un autre arbitrage : quel système possède le comptage et quelles modifications concurrentes doit-il préserver ? Le choix entre valeur absolue et delta se décide avec la logistique. Transformer silencieusement un delta incertain en stock absolu peut masquer le doublon tout en écrasant des ventes intervenues depuis la réception. La réparation technique doit rester compatible avec la politique de stock.

Anatomie d’une réception : intention, destination, requête et preuve

Donner une identité durable à l’opération physique

Un dossier de réception conserve le logiciel émetteur, l’établissement, le document et la ligne. Ces dimensions distinguent deux bons portant le même numéro dans deux sociétés. Le mapping résout ensuite l’article d’inventaire Shopify et son emplacement. Le SKU permet au magasinier de reconnaître le produit ; il ne remplace pas les identifiants effectivement employés par l’API, notamment lorsqu’une référence a changé de destination.

Une correction de la réception possède sa propre histoire. Si le magasinier annule cinq pièces et en valide quatre, le connecteur ne modifie pas rétroactivement le payload d’une opération déjà envoyée. Il retrouve d’abord son issue, puis représente la correction autorisée. Une référence stable reste attachée au fait initial ; elle ne devient pas une enveloppe dans laquelle chaque relance introduit le dernier comptage disponible.

Enregistrer avant l’envoi, puis retrouver après le redémarrage

Le journal doit résister à l’arrêt du worker après émission. Enregistrez l’intention, la clé, la requête et le statut préparé dans un stockage durable avant de commencer la tentative. Un simple log écrit après réception du résultat laisse précisément un vide lorsque la réponse se perd. La recette interrompt le processus à cette frontière, redémarre l’application et vérifie qu’elle reprend le même dossier.

Conservez séparément la date de préparation et celle de la première tentative. La seconde détermine votre prudence sur la protection fournisseur. Un dossier préparé lundi mais envoyé mardi ne doit pas hériter d’un délai calculé arbitrairement depuis sa création. Le journal local garde une estimation conservatrice de l’envoi et les incertitudes d’horloge ; il ne prétend pas observer directement le début de la rétention dans Shopify.

Choisir la clé à partir de l’intention, pas du numéro de tentative

Conserver la clé quand la même réception est rejouée

La note Shopify sur l’idempotence obligatoire impose la directive @idempotent pour ces ajustements à partir de 2026-04. Après un timeout, la reprise du même dossier conserve la clé et ses paramètres. Le numéro de tentative peut augmenter dans vos traces ; il ne doit pas fabriquer une nouvelle identité d’ajustement.

Un UUID généré à chaque appel transforme une reprise réseau en nouvelle demande. À l’inverse, une clé dérivée uniquement du produit et du delta peut réunir deux réceptions différentes. Concevez une identité de mouvement puis associez-lui une clé durable. Une contrainte d’unicité locale empêche deux workers de préparer deux clés pour le même fait, et une autre empêche leur réutilisation pour deux intentions distinctes.

Ne pas dédupliquer deux arrivages réellement différents

Dans un premier scénario fictif, deux camions livrent chacun cinq unités du même article au même dépôt. Leurs paramètres de quantité peuvent se ressembler, mais leurs réceptions sont distinctes. Le connecteur prépare deux opérations, avec deux clés. La logistique doit retrouver les deux documents dans le journal, même si le premier arrivage et le second se produisent dans la même minute.

Le même raisonnement s’applique aux lignes d’un lot. Une clé unique pour tout l’import ne décrit pas correctement les intentions si chaque ligne devient une mutation indépendante. La documentation des requêtes idempotentes Shopify précise aussi le fonctionnement par ligne pour les opérations bulk compatibles. Le découpage réel du connecteur doit rester visible : document métier, ligne et requête sont liés, mais ne sont pas toujours interchangeables.

Comprendre ce que changeFromQuantity protège

Contrôler la quantité attendue avant le delta

La note sur le champ désormais requis demande une valeur explicite à partir de 2026-04. Avec changeFromQuantity: 12, la modification attend douze unités avant l’application du delta. Une quantité différente produit CHANGE_FROM_QUANTITY_STALE. Le schéma peut présenter le champ comme nullable alors que son omission échoue à l’exécution ; la validation statique seule ne suffit donc pas.

Paradoxalement, deux réceptions correctes peuvent produire un rejet de quantité parce qu’elles ont lu le même état initial. Ce contrôle ne remplace donc pas l’identité du mouvement. Le connecteur doit examiner le rejet et réévaluer la quantité pour la demande qui n’a pas été appliquée, selon la règle de stock approuvée. Il ne transforme pas automatiquement toute discordance en autorisation de remplacer le comptage Shopify.

Justifier une désactivation plutôt que la cacher dans le code

Le type InventoryChangeInput documente la possibilité de transmettre null pour ne pas comparer la quantité. Cela peut correspondre à une source de vérité de stock clairement désignée. Ce choix supprime une protection de concurrence ; il doit être justifié par le fonctionnement des écritures au dépôt, et non par le souhait de faire disparaître une erreur du tableau de bord.

Listez les autres acteurs qui modifient l’état visé : ventes, préparation, inventaire et interventions d’administration selon votre configuration. Le rôle de chaque système doit être compris avant le choix du paramètre. Si le connecteur ne sait pas expliquer pourquoi un autre acteur a changé la quantité, il ne possède pas encore la preuve nécessaire pour qualifier un conflit comme une anomalie à écraser.

Préparer une requête dont les paramètres restent lisibles

Séparer le modèle interne de la mutation fournisseur

Le connecteur peut recevoir un document WMS riche, puis produire une requête Shopify beaucoup plus courte. Conservez les deux avec leur version de transformation. Le code suivant illustre une mutation avec variables et directive ; les identifiants et la réception sont fictifs. Il décrit un ajout sur available pour un couple déjà qualifié, pas une politique universelle de conversion de tout stock ERP en disponible à vendre.

mutation ReceiptAdjustment(
  $input: InventoryAdjustQuantitiesInput!,
  $key: String!
) {
  inventoryAdjustQuantities(input: $input) @idempotent(key: $key) {
    inventoryAdjustmentGroup { id }
    userErrors { code field message }
  }
}

{
  "key": "receipt-104-line-1",
  "input": {
    "reason": "received",
    "name": "available",
    "changes": [{
      "inventoryItemId": "gid://shopify/InventoryItem/8001",
      "locationId": "gid://shopify/Location/9001",
      "delta": 5,
      "changeFromQuantity": 12
    }]
  }
}

Refuser un changement de payload pendant une reprise incertaine

Le dossier conserve le payload envoyé ; une empreinte locale peut aider à détecter sa modification accidentelle. Cette empreinte appartient à votre journal et ne reproduit pas l’algorithme de comparaison Shopify. Elle accompagne le contenu réellement conservé, l’ordre des lignes et les paramètres de la mutation. Un hash isolé permet de constater un changement, mais pas de reconstruire l’opération perdue.

Si une nouvelle lecture indique seize unités, ne remplacez pas douze par seize sous la clé d’une tentative encore incertaine. Vous avez changé la requête avant d’avoir retrouvé son issue. Le support conserve la nouvelle observation dans le dossier, puis traite séparément la décision qui pourrait justifier une autre opération. Une lecture plus récente enrichit l’enquête ; elle n’autorise pas à réécrire l’historique envoyé.

Classer les retours avant de programmer la relance

Ne pas transformer HTTP 200 en confirmation logistique

Le parseur distingue la réponse réseau, les erreurs GraphQL et les userErrors de la mutation. Une réponse HTTP reçue n’atteste pas à elle seule l’ajustement. Une réponse absente n’atteste pas davantage son rejet. Le statut interne doit nommer cette différence : confirmé avec preuve attribuable, rejet reçu, ou issue encore inconnue. Les files de reprise correspondent à ces situations plutôt qu’au seul succès du transport.

Un conflit de quantité connu part vers la revue du mouvement et du comptage. Une erreur d’identité ou d’autorisation part vers la correction de configuration. Une réponse incompréhensible garde le dossier incertain. Le monitoring montre le motif exact et la dernière preuve disponible, sans enregistrer de jeton OAuth dans les logs ni exposer tout le document fournisseur à un utilisateur qui n’en a pas besoin.

Distinguer concurrence, changement de paramètres et perte de réponse

La note d’idempotence nomme IDEMPOTENCY_CONCURRENT_REQUEST lorsqu’une demande portant cette clé est encore en cours, et IDEMPOTENCY_KEY_PARAMETER_MISMATCH lorsque les paramètres diffèrent. La première situation appelle une attente bornée et une reprise identique ; la seconde impose d’examiner votre journal. Changer la clé pour contourner l’erreur supprimerait le lien qui devait protéger le mouvement initial.

La stratégie de backoff évite des demandes simultanées sur le même dossier. Elle conserve la clé, les paramètres et un prochain instant de tentative, avec une échéance locale de revue. Une file ne doit pas relancer éternellement une erreur permanente. Le responsable du connecteur peut suspendre une réception ou une boutique, puis reprendre les dossiers qualifiés sans réinitialiser les identités des autres mouvements.

Traiter une reprise tardive après la fenêtre de protection

Le journal doit durer plus longtemps que la déduplication fournisseur

La documentation d’implémentation indique une rétention de vingt-quatre heures depuis la requête initiale pour les mutations utilisant cette directive. Après cette fenêtre, le rejeu n’est plus reconnu comme doublon. Elle précise aussi qu’une réponse de reprise peut rarement refléter un état de base modifié : son contenu ne constitue pas nécessairement une photographie historique immuable.

Votre règle locale prévoit une marge pour l’horloge et le transport, puis arrête l’envoi automatique avant de supposer la protection expirée ou encore disponible. Le dossier reste conservé pour la réconciliation. Une indisponibilité de plusieurs jours n’efface donc ni la réception ni son incertitude. Le retour du réseau doit faire réapparaître une file à qualifier, pas déclencher mécaniquement tous les anciens deltas.

Une quantité actuelle ne prouve pas le sort d’un ancien mouvement

Dans un second scénario fictif, un stock initial de douze reçoit cinq unités, puis trois ventes interviennent. Une lecture à quatorze peut être cohérente avec la réception appliquée ; d’autres mouvements peuvent néanmoins produire le même total. La quantité seule n’identifie pas la réception. L’enquête rapproche les documents WMS, les requêtes et réponses conservées et les traces d’ajustement effectivement disponibles dans la configuration retenue.

Si ces preuves restent insuffisantes, la décision appartient au responsable de stock, avec comptage ou rapprochement complémentaire. Le connecteur ne fabrique pas une certitude à partir d’une égalité numérique. Une correction validée reçoit sa propre identité et une justification liée à l’incident initial. Le support doit pouvoir expliquer quelle opération est confirmée, laquelle est compensée et laquelle reste indéterminée.

Atelier local : sept dossiers de réception à classer

Exécuter une politique de reprise sans appeler Shopify

Le programme Python de l’atelier prend une réception fictive, ses paramètres conservés, un état local et un temps écoulé. Il n’envoie aucune requête et ne simule pas une garantie serveur. Son rôle est de vérifier les refus de votre politique : payload changé, conflit connu, dossier déjà confirmé ou reprise trop ancienne.

Exécutez python3 stock_inventory.py avec Python 3.10 ou supérieur. Quinze assertions vérifient sept dossiers et plusieurs invariants. Le seuil de vingt-trois heures est une marge illustrative choisie dans cet exercice, distincte des vingt-quatre heures documentées par Shopify. Son adaptation exige les mesures et les contraintes d’horloge de votre architecture ; elle ne constitue pas un seuil recommandé pour toutes les boutiques.

• Un premier envoi conserve une intention déjà préparée.
• Un timeout après deux heures propose la même clé et les mêmes paramètres.
• Une réception confirmée reste close sans nouvel ajustement.
• Une reprise après vingt-cinq heures demande un rapprochement avant envoi.
• La marge locale à vingt-trois heures produit le même arrêt conservateur.
• Un conflit de quantité reçu impose une revue du comptage.
• Une quantité attendue changée bloque la reprise de la requête d’origine.

Ajouter une recette réelle pour les frontières non simulées

L’exercice montre aussi que deux réceptions différentes peuvent partager un payload sans partager une clé. Il ne valide ni les droits Shopify, ni la disponibilité de l’article dans l’emplacement, ni l’ordre réel de traitement des mutations. Ces points restent à éprouver dans un environnement de recette avec les interfaces, la version et les états de stock effectivement employés par votre connecteur.

La recette injecte une perte de réponse après réception serveur, un arrêt de worker, deux exécuteurs concurrents et un changement de quantité entre lecture et écriture. Chaque scénario retrouve la réception et ses paramètres. Le constat attendu porte sur le nombre d’effets attribuables au mouvement et sur la décision de reprise, pas seulement sur la couleur du job dans l’outil d’orchestration.

Erreurs fréquentes : les raccourcis qui doublent ou masquent le stock

Réparer le transport en changeant le fait métier

La première erreur génère une nouvelle clé à chaque timeout. La deuxième réutilise une clé commune à toutes les réceptions du même produit. La troisième met à jour la quantité attendue sous une clé déjà envoyée. Elles touchent la même frontière : le connecteur ne sait plus si la requête représente le fait initial ou une décision différente. Le journal doit permettre de refuser ces trois transformations.

Un autre raccourci remplace le delta incertain par une quantité absolue lue dans l’ERP. Cette écriture peut donner un écran cohérent tout en effaçant des engagements locaux. Si une politique de réconciliation autorise une valeur absolue, elle doit être qualifiée et tracée comme telle. Le support retrouve la raison, la population de mouvements considérée et les modifications concurrentes que la correction prend en compte.

Clore trop vite ou laisser la file perdre son responsable

Une réception peut rester techniquement en attente après que l’opérateur a corrigé le stock manuellement. La file doit recevoir cette décision, sinon elle pourra l’ajouter plus tard. À l’inverse, fermer un dossier parce que sa quantité paraît plausible efface une incertitude encore réelle. La clôture conserve la preuve observée et l’identité de la personne ou du traitement qui l’a qualifiée.

Surveillez l’âge des dossiers sans issue, les tentatives concurrentes, les changements de paramètres refusés et les mouvements dépassant la marge locale. Un signal faible apparaît quand les clés changent après un redémarrage ; un autre quand la file se vide sans nouvelles confirmations attribuables. Ces observations conduisent à relire la reprise et la clôture, plutôt qu’à simplement augmenter le nombre de workers.

Plan d’action : reprendre une réception avant d’étendre au dépôt

Rassembler un dossier que la logistique peut reconnaître

Choisissez une réception réelle dont la réponse manque, puis rassemblez le document WMS, sa ligne, la boutique, l’article et l’emplacement. Le partenaire ERP vérifie l’origine du mouvement et sa validation. Le mainteneur du connecteur fournit la version d’API, la requête envoyée, la clé conservée et les retours disponibles. Dawap peut relier ces preuves et identifier l’endroit où l’application perd l’intention ou son issue.

Écrivez les états internes et les transitions autorisées : préparé, envoyé sans résultat, rejet qualifié, confirmé ou revue nécessaire. Le runbook relie la journalisation de chaque tentative à sa file de reprise et attribue la revue tardive au responsable de stock. La suspension d’un dépôt garde les opérations déjà engagées ; elle ne remet pas la file à zéro et n’efface pas les clés au prochain redémarrage.

Exiger les preuves de reprise et une possibilité de repli

Avant l’extension, exécutez les cas locaux puis la recette du connecteur. Vérifiez la conservation des paramètres, l’attribution des réponses et les refus après expiration de votre marge. Comparez le journal avant et après arrêt du worker. Contrôlez aussi les autorisations OAuth et le périmètre des logs. Le feu vert exige que l’équipe puisse expliquer les dossiers refusés autant que ceux qui se sont terminés.

Le seuil d’arrêt du pilote est atteint lorsqu’une réception reçoit deux clés, qu’une requête incertaine change de payload ou qu’un effet ne peut plus être attribué. Le monitoring expose ces dossiers dans la file de revue ; le repli suspend les nouveaux ajustements automatiques du périmètre concerné. L’extension suit des mouvements qualifiés, puis un dépôt ; elle ne transforme pas la réussite d’un exemple en validation de toutes les politiques de stock.

• À conserver : le document initial, la destination résolue, la clé et les paramètres effectivement envoyés.
• À contrôler d’abord : la dernière issue attribuable et l’ancienneté de la première tentative.
• À refuser : une nouvelle clé pour contourner une réponse manquante ou un changement de payload non décidé.
• À valider ensuite : une éventuelle correction de stock, avec son responsable et une identité distincte.

Mesurez les reprises manuelles réellement observées, leur durée et l’âge des mouvements non confirmés. Le coût caché comprend la recherche du document, le rapprochement avec l’entrepôt et la décision de correction. Une baisse des retries n’est pas un gain si l’équipe ne retrouve plus les réceptions. Le critère de livraison reste la capacité du remplaçant à reprendre un incident avec le journal et la procédure.

Lectures complémentaires : protéger les autres frontières du connecteur

Qualifier le transport et le périmètre Shopify

Le dossier Shopify API GraphQL : commandes, produits et webhooks situe les objets du raccordement. Il sert à vérifier le périmètre global lorsque l’incident de réception révèle une correspondance incomplète entre les références du commerce et celles du logiciel logistique.

Le diagnostic Shopify GraphQL THROTTLED : isoler la boutique concernée précise le traitement d’une pression API sans pénaliser les autres boutiques. La limitation de débit et l’incertitude d’écriture restent deux problèmes distincts, même lorsqu’ils se rencontrent dans la même file.

Conserver les décisions qui traversent plusieurs systèmes

Le contrat d’échange ERP–e-commerce rassemble les conventions de mapping, de versioning et de reprise. Il aide à formaliser qui possède le mouvement, qui transforme la requête et qui confirme l’effet, lorsque plusieurs prestataires se partagent le connecteur.

Le runbook d’incident API organise l’enquête et la passation. Pour les réceptions Shopify, ses étapes doivent pointer vers le journal de mouvement et les décisions de revue tardive ; une consigne générale de relance ne suffit pas à protéger un delta incertain.

Conclusion : préserver la réception pendant toutes ses tentatives

Une réception physique conserve son identité même lorsque le réseau se coupe. La reprise du connecteur garde la requête et sa clé, puis recherche une issue attribuable. Le contrôle de quantité ajoute une protection de concurrence ; il ne remplace ni le journal ni la décision sur le fait que l’on veut appliquer.

L’évolution 2026-04 oblige à expliciter ces deux paramètres. Leur valeur réelle dépend cependant de la manière dont l’application les prépare, les conserve et les retrouve après un arrêt. Une clé nouvelle ou un payload modifié pendant une reprise peut annuler le bénéfice attendu, même si la requête contient tous les champs exigés.

La protection fournisseur possède une fenêtre limitée. Une réception ancienne et incertaine appelle une réconciliation, avec les preuves disponibles et un responsable de stock. Les sept dossiers de l’atelier éprouvent cette politique localement ; la recette réelle doit encore établir les effets et les droits du connecteur dans votre environnement.

Dawap accompagne cette reprise dans le cadrage de vos échanges API. Nous partons des mouvements identifiés, vérifions le journal et définissons avec vos intervenants une recette de timeout, de conflit et de reprise tardive que l’équipe logistique pourra exploiter.