API de modification de commande Shopify : un flux fiable de l’ouverture à la validation

Pourquoi les 3 étapes de l’API comptent#

Modifier une commande est une transaction, pas une simple mise à jour. Shopify crée une version calculée de la commande. L’application y prépare les modifications, puis applique cette version lorsqu’elle valide la modification.

Sur plus de 10 millions de commandes passées dans des boutiques utilisant Revize, environ 1 commande sur 19, soit 5,2 %, a été modifiée après le paiement (Revize, 2026). Ce volume justifie de traiter la modification des commandes comme une opération courante plutôt que comme une exception gérée par le service client.

Le CalculatedOrder ressemble à une copie de contrôle d’une liste de prélèvement en entrepôt. Vous pouvez y ajouter ou retirer des lignes, examiner le résultat, puis publier une version définitive.

Le moment de la modification compte autant que la justesse des appels API. Dans les boutiques utilisant Revize, la modification médiane intervient 4,6 minutes après le paiement (Revize, 2026). Si la préparation commence pendant cet intervalle, même un code techniquement correct peut aboutir à un colis erroné.

Fonctionnement de l’API de modification de commande Shopify#

Avec l’API Shopify Admin 2026-07, le flux comprend orderEditBegin, une ou plusieurs mutations de préparation, puis orderEditCommit. Les références des mutations Shopify acceptent l’ID de la commande calculée ou celui de la session de modification pour la préparation et la validation. Ce guide utilise systématiquement calculatedOrder.id.

1. Appelez orderEditBegin avec l’ID de la commande Shopify.
2. Enregistrez calculatedOrder.id dans $calculatedOrderId.
3. Exécutez chaque mutation de préparation avec cet ID.
4. Examinez les lignes calculées, les totaux et chaque tableau userErrors.
5. Transmettez le même ID à orderEditCommit.

Shopify décrit ce modèle d’ouverture, de préparation et de validation. L’application doit disposer du champ d’autorisation write_order_edits.

Une mutation d’ouverture minimale peut demander les deux objets à des fins de diagnostic, tout en ne retenant qu’un seul identifiant pour la suite du flux :

mutation BeginOrderEdit($orderId: ID!) {
  orderEditBegin(id: $orderId) {
    calculatedOrder {
      id
      lineItems(first: 50) {
        nodes {
          id
          quantity
        }
      }
    }
    orderEditSession {
      id
    }
    userErrors {
      field
      message
    }
  }
}

Arrêtez-vous si userErrors n’est pas vide. Une requête réseau réussie prouve seulement que Shopify l’a reçue, pas que l’opération a été acceptée.

Le guide de modification correspondant à cette version de l’API décrit les opérations de préparation pour les variantes, les quantités, les articles personnalisés, les remises sur les lignes de commande et les lignes d’expédition. Consultez la référence de la mutation 2026-07 concernée avant de commencer l’implémentation, puis avant tout changement de version de l’API.

Comment remplacer complètement une variante#

Pour remplacer une variante, ajoutez la nouvelle et ramenez à zéro la quantité de la ligne calculée d’origine dans une même session de modification. Ne validez qu’après la réussite des deux opérations et après avoir vérifié que le résultat calculé correspond à ce que le client a confirmé.

Supposons qu’un client ait commandé une taille M et souhaite une taille L.

1. Ouvrez la modification et enregistrez calculatedOrder.id.
2. Ajoutez la variante en taille L avec cet ID :

mutation AddReplacement(
  $calculatedOrderId: ID!
  $variantId: ID!
  $quantity: Int!
) {
  orderEditAddVariant(
    id: $calculatedOrderId
    variantId: $variantId
    quantity: $quantity
  ) {
    calculatedLineItem {
      id
      quantity
    }
    userErrors {
      field
      message
    }
  }
}

3. Repérez la taille M d’origine dans la commande calculée. Utilisez l’ID de sa ligne calculée au lieu de reprendre l’ID d’une ligne de la commande initiale sans vérifier l’état calculé renvoyé.

4. Ramenez la quantité de la ligne d’origine à zéro :

mutation RemoveOriginal(
  $calculatedOrderId: ID!
  $lineItemId: ID!
) {
  orderEditSetQuantity(
    id: $calculatedOrderId
    lineItemId: $lineItemId
    quantity: 0
  ) {
    calculatedLineItem {
      id
      quantity
    }
    userErrors {
      field
      message
    }
  }
}

5. Interrogez de nouveau la commande calculée. Vérifiez que la nouvelle variante est présente, que la quantité de l’ancienne est nulle et que les totaux correspondent à la confirmation du client.
6. Validez avec le même ID de commande calculée :

mutation CommitOrderEdit(
  $calculatedOrderId: ID!
  $notifyCustomer: Boolean!
  $staffNote: String
) {
  orderEditCommit(
    id: $calculatedOrderId
    notifyCustomer: $notifyCustomer
    staffNote: $staffNote
  ) {
    order {
      id
      updatedAt
    }
    userErrors {
      field
      message
    }
  }
}

Attention : Ne validez pas si l’ajout a réussi, mais que la suppression n’a pas encore réussi. Le remplacement deviendrait un article supplémentaire.

Rejetez les clics de confirmation en double, consignez l’étape terminée et récupérez de nouveau la commande avant validation si un autre processus a pu la modifier.

Quelle mutation utiliser pour chaque modification#

Utilisez le flux de commande calculée pour les lignes de commande, les quantités, les remises et les changements de lignes d’expédition. Réservez orderUpdate, les mutations d’annulation et celles de remboursement aux opérations décrites dans leurs références pour la version utilisée.

La référence 2026-07 de orderUpdate couvre des attributs comme l’adresse e-mail du client, l’adresse de livraison, les balises et les métachamps. Ses exemples montrent aussi la mise à jour de la note. Elle renvoie les changements importants, comme l’ajout ou la suppression de lignes de commande, le changement de quantités ou la modification de remises, vers orderEditBegin.

Les restrictions de Shopify sur la modification des commandes précisent que les codes de réduction, les réductions automatiques et les réductions appliquées par script ne peuvent pas être modifiés. Les remises à l’échelle de la commande ne peuvent pas non plus être ajoutées, supprimées ou changées. Les mutations de remise sur une ligne de commande ne lèvent pas ces restrictions.

Les limites de l’API de modification de commande Shopify#

La validation d’une modification et son règlement financier sont deux étapes distinctes. Shopify précise qu’une modification du total peut laisser un solde à payer par le client ou nécessiter un remboursement.

Si le total augmente, récupérez la commande validée et vérifiez comment le solde sera encaissé avant de la transmettre au traitement des commandes (fulfillment). Une réponse positive de orderEditCommit ne prouve pas que le paiement est terminé.

Si le total diminue, la validation ne remplace pas une procédure de remboursement délibérée. Calculez le montant voulu, appelez l’opération de remboursement appropriée et examinez sa réponse. Une modification sans différence de montant ne nécessite ni encaissement ni remboursement, mais exige tout de même une dernière vérification de l’état de la commande.

Abonnez-vous au webhook Shopify orders/edited, puis récupérez de nouveau la commande avant qu’un système en aval n’agisse. Un webhook signale qu’il faut lire l’enregistrement actuel ; il ne garantit pas qu’une copie locale antérieure soit encore exacte.

Ne laissez jamais un prestataire logistique tiers, ou 3PL, préparer une commande dont la modification ou la situation financière n’est pas résolue. Testez la mise en attente, la règle liée au statut de paiement ou le signal de libération avec le système d’entrepôt qui télécharge réellement les commandes.

Comment diagnostiquer les échecs de modification#

Vérifiez d’abord l’admissibilité de la commande, les identifiants, la validation et les modifications concurrentes. Consignez le nom de la mutation, l’ID de la commande Shopify, l’ID de modification retenu et le tableau userErrors complet, sans enregistrer de données sensibles sur le client ou le paiement.

Les conditions de modification des commandes de Shopify indiquent que les applications ont besoin de write_order_edits, ne peuvent modifier que les lignes non traitées et ne peuvent modifier ni les commandes archivées ni celles passées avant le 1er janvier 2019. Par défaut, les applications ont accès aux commandes des 60 derniers jours ; interroger des commandes plus anciennes nécessite read_all_orders.

Ces règles sont distinctes. read_all_orders donne accès à des enregistrements plus anciens, mais ne rend pas modifiable une commande archivée ou passée avant 2019.

N’adaptez pas le comportement de l’application à un message d’erreur supposé. Lisez le champ et le message renvoyés pour la requête concernée, puis reproduisez l’échec avec une commande de test contrôlée.

Utiliser Revize ou développer avec les API#

Revize est le choix le plus direct si vous voulez permettre aux clients de modifier eux-mêmes leur commande avant le traitement ; un développement sur mesure convient à une orchestration interne propre à votre entreprise. Vous choisissez entre un parcours client fourni par l’application et la gestion de chaque interface, transition et protection du flux d’entrepôt.

Le développement sur mesure a sa place lorsqu’un marchand a besoin d’une interface réservée à son personnel ou d’un processus d’approbation couvrant plusieurs systèmes internes. Revize ne propose ni API générale de modification des commandes ni file d’approbation pour les marchands.

Les agences peuvent relier les déclencheurs Shopify Flow documentés aux événements de modification de Revize, utiliser les balises de modification et de libération de Revize dans la logique de traitement des commandes, ou utiliser la Public Cancellation API pour une interface d’annulation externe. La Public Cancellation API est réservée à Pro, nécessite une activation par l’assistance et applique la fenêtre de modification, les restrictions et la politique de remboursement du portail.

Parmi les modifications après achat dans les boutiques utilisant Revize, 92,2 % ont été effectuées par les clients sans intervention du service client (Revize, 2026). Le guide de modification des commandes après achat pour les agences présente le travail de cadrage à effectuer avant l’implémentation.

La disponibilité des fonctionnalités dépend du forfait. L’ajout et le remplacement de produits, les remboursements en avoir, le recalcul des remises, des frais d’expédition et des taxes, le moteur de règles, Reverse Unpaid Edits et la Public Cancellation API sont réservés à Pro, comme l’indique la documentation de facturation de Revize.

Installez Revize: Order Editing & Upsell si vous souhaitez proposer aux clients un parcours de modification en libre-service.

Comment Revize complète le parcours#

Revize propose aux clients un parcours de modification encadré sur la page de statut de la commande Shopify. Le marchand définit la fenêtre de modification, les actions disponibles, la politique de remboursement et le mode de traitement des commandes.

Lorsqu’une modification augmente le total, Revize affiche Pay now et redirige le client vers la page de paiement Shopify uniquement pour régler la différence. Si le total diminue, Revize affiche Refund ; s’il reste inchangé, Confirm. Shopify exécute le paiement ou le remboursement, comme l’explique le parcours client Revize.

Le marchand règle la durée dans Order Editing > Order edit window. Le guide de configuration de la fenêtre de modification décrit les durées prédéfinies, les durées personnalisées, les heures limites programmées et le mode « jusqu’au traitement de la commande ». Ce dernier ne met pas, à lui seul, une commande en attente.

Avec le mode de traitement recommandé, Revize applique une mise en attente du traitement des commandes dans Shopify pendant la fenêtre de modification, puis la lève lorsque la fenêtre se ferme. Les systèmes qui ignorent ces mises en attente peuvent nécessiter la solution de repli documentée de capture manuelle du paiement. Une balise de libération peut aussi avertir un système de traitement configuré pour attendre cette balise.

Revize vérifie le stock en temps réel, en tenant compte de la zone d’expédition, avant d’autoriser le client à remplacer une variante. Le guide sur la mise en attente du traitement des commandes couvre la partie du parcours qui concerne l’entrepôt.

Que tester cette semaine#

Testez une commande du paiement jusqu’au traitement corrigé, y compris les cas d’échec. Une mutation réussie dans un client GraphQL n’est que la première vérification.

1. Créez une commande de développement ou une commande provisoire représentative.
2. Testez un remplacement à prix égal, une augmentation et une diminution du montant.
3. Examinez userErrors après l’ouverture, chaque mutation de préparation et la validation.
4. Vérifiez la commande calculée avant de valider.
5. Vérifiez séparément l’encaissement et la gestion du remboursement.
6. Faites passer la commande modifiée par le véritable système de traitement des commandes.
7. Testez une commande archivée, une commande ancienne, des tentatives simultanées et un abandon en cours de modification.
8. Consultez les limites de la modification native des commandes Shopify avant le passage en production.