Shopify API voor bestellingen bewerken: bouw een veilige flow van start tot bevestiging

Waarom de drie API-stappen belangrijk zijn#

Een bestelling bewerken is een transactie, geen losse update. Shopify maakt een berekende versie van de bestelling. De app zet daar wijzigingen in klaar en past die versie vervolgens toe wanneer de app de bewerking bevestigt.

Van meer dan 10 miljoen bestellingen bij winkels die Revize gebruiken, werd ongeveer 1 op de 19 bestellingen, of 5,2%, na de checkout bewerkt (Revize, 2026). Dat is genoeg om het bewerken van bestellingen als een vast werkproces in te richten, in plaats van als uitzondering voor de klantenservice.

De CalculatedOrder lijkt op een proefversie van een picklijst voor het magazijn. Je kunt regels toevoegen en verwijderen, het resultaat controleren en daarna één definitieve versie vastleggen.

De timing is net zo belangrijk als correcte API-aanroepen. Bij winkels die Revize gebruiken, vindt de middelste bewerking 4,6 minuten na de checkout plaats (Revize, 2026). Als het verzamelen van producten in die periode begint, kan technisch correcte code toch tot het verkeerde pakket leiden.

Hoe de Shopify API voor het bewerken van bestellingen werkt#

Voor Shopify Admin API 2026-07 bestaat de flow uit orderEditBegin, een of meer mutaties om wijzigingen klaar te zetten en daarna orderEditCommit. Volgens de mutatiereferenties van Shopify kun je voor de tussenstappen en de bevestiging zowel de ID van de berekende bestelling als die van de bewerksessie gebruiken. Deze handleiding gebruikt consequent calculatedOrder.id.

1. Roep orderEditBegin aan met de ID van de Shopify-bestelling.
2. Sla calculatedOrder.id op als $calculatedOrderId.
3. Voer elke mutatie om wijzigingen klaar te zetten uit met die ID.
4. Controleer de berekende bestelregels, de totalen en elke userErrors-lijst.
5. Geef dezelfde ID door aan orderEditCommit.

Shopify beschrijft dit model van starten, wijzigingen klaarzetten en bevestigen. De app heeft de toegangsscope write_order_edits nodig.

Een minimale mutatie om de bewerking te starten kan beide objecten opvragen voor foutdiagnose, terwijl je één ID kiest voor de rest van de flow:

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

Stop als userErrors niet leeg is. Een geslaagd netwerkverzoek bewijst alleen dat Shopify het verzoek heeft ontvangen, niet dat de bewerking is geaccepteerd.

De versiegebonden handleiding voor het bewerken van bestellingen beschrijft mutaties voor varianten, aantallen, aangepaste artikelen, kortingen op bestelregels en verzendregels. Controleer de relevante mutatiereferentie voor 2026-07 voordat je begint met implementeren en opnieuw voordat je van API-versie verandert.

Een variant volledig omwisselen#

Om een variant om te wisselen, voeg je de vervangende variant toe en zet je het aantal van de oorspronkelijke berekende bestelregel binnen dezelfde bewerksessie op nul. Bevestig de bewerking pas als beide stappen zijn geslaagd en het berekende resultaat overeenkomt met wat de klant heeft bevestigd.

Stel dat een klant een maat M heeft besteld en een maat L nodig heeft.

1. Start de bewerking en sla calculatedOrder.id op.
2. Voeg met die ID de variant in maat L toe:

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

3. Zoek de oorspronkelijke maat M in de berekende bestelling. Gebruik de ID van de berekende bestelregel. Neem de ID van een regel uit de oorspronkelijke bestelling niet over zonder de geretourneerde berekende gegevens te controleren.

4. Zet het aantal van de oorspronkelijke regel op nul:

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

5. Vraag de berekende bestelling opnieuw op. Controleer of de vervangende variant aanwezig is, het aantal van de oorspronkelijke variant nul is en de totalen overeenkomen met de bevestiging van de klant.
6. Bevestig de bewerking met dezelfde ID van de berekende bestelling:

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

Waarschuwing: Bevestig de bewerking niet als het toevoegen is gelukt maar het verwijderen nog niet. Anders wordt de omwisseling een extra artikel.

Wijs herhaalde klikken op de bevestigingsknop af, leg vast welke stap is afgerond en haal de bestelling opnieuw op voordat je bevestigt als een ander proces de bestelling kan hebben gewijzigd.

Welke mutatie gebruik je voor welke bewerking?#

Gebruik de flow met de berekende bestelling voor wijzigingen aan bestelregels, aantallen, kortingen en verzendregels. Gebruik orderUpdate en mutaties voor annuleringen en terugbetalingen alleen voor de taken die in de bijbehorende versiegebonden referenties staan.

De referentie voor orderUpdate in 2026-07 behandelt kenmerken zoals het e-mailadres van de klant, het verzendadres, tags en metafields. De voorbeelden laten ook zien hoe je opmerkingen bijwerkt. Voor ingrijpende wijzigingen, zoals het toevoegen of verwijderen van bestelregels, het wijzigen van aantallen of het aanpassen van kortingen, verwijst de referentie naar orderEditBegin.

Volgens Shopify’s aandachtspunten voor het bewerken van bestellingen kun je kortingscodes, automatische kortingen en scriptkortingen niet bewerken. Kortingen op bestelniveau kun je ook niet toevoegen, verwijderen of wijzigen. Mutaties voor kortingen op bestelregels veranderen niets aan die beperkingen.

Waar de Shopify API voor het bewerken van bestellingen ophoudt#

Een bevestigde bewerking en de financiële afhandeling zijn aparte controlepunten. Shopify geeft aan dat een wijziging in het totaalbedrag ertoe kan leiden dat de klant een openstaand bedrag moet betalen of een terugbetaling moet ontvangen.

Haal bij een hoger totaal de bevestigde bestelling opnieuw op en controleer hoe je het openstaande bedrag int voordat je de bestelling vrijgeeft voor fulfillment (orderafhandeling). Beschouw een geslaagde reactie van orderEditCommit niet als bewijs dat de betaling is afgerond.

Bij een lager totaal vervangt het bevestigen van de bewerking geen aparte procedure voor terugbetaling. Bereken het bedoelde bedrag, roep de juiste terugbetalingsmutatie aan en controleer de reactie. Als het totaal niet verandert, hoef je niets te innen of terug te betalen. Je moet wel de uiteindelijke status van de bestelling controleren.

Abonneer je op Shopify’s webhook voor orders/edited en haal de bestelling opnieuw op voordat een volgend systeem actie onderneemt. Een webhook is een signaal om de actuele gegevens te lezen, geen reden om op een eerder opgeslagen lokale kopie te vertrouwen.

Laat een externe logistieke dienstverlener, of 3PL, geen bestelling verzamelen zolang de bewerking of financiële afhandeling nog openstaat. Test de blokkering, de regel voor de betaalstatus of het vrijgavesignaal met het magazijnsysteem dat de bestellingen daadwerkelijk ophaalt.

Fouten bij het bewerken opsporen#

Begin met de bewerkbaarheid van de bestelling, ID’s, validatie en gelijktijdige wijzigingen. Leg de naam van de mutatie, de ID van de Shopify-bestelling, de gekozen bewerkings-ID en de volledige userErrors-lijst vast, zonder klantgegevens of betaalgegevens op te slaan.

Volgens Shopify’s vereisten voor het bewerken van bestellingen hebben apps write_order_edits nodig, kunnen ze alleen bestelregels bewerken die nog niet zijn afgehandeld en kunnen ze geen gearchiveerde bestellingen of bestellingen van vóór 1 januari 2019 bewerken. Apps hebben standaard toegang tot bestellingen van de afgelopen 60 dagen. Voor het opvragen van oudere bestellingen is read_all_orders nodig.

Dit zijn afzonderlijke regels. read_all_orders geeft toegang tot oudere gegevens, maar maakt een gearchiveerde bestelling of een bestelling van vóór 2019 niet bewerkbaar.

Baseer het gedrag van je app niet op een gegiste foutmelding. Lees het geretourneerde veld en bericht van het specifieke verzoek en reproduceer de fout met een gecontroleerde testbestelling.

Revize gebruiken of zelf met API’s bouwen#

Revize is doorgaans de beste keuze als klanten hun bestelling vóór fulfillment zelf moeten kunnen aanpassen. Maatwerkcode past bij bedrijfseigen processen tussen interne systemen. Je kiest tussen een kant-en-klaar klanttraject en zelf alle schermen, statusovergangen en waarborgen voor het magazijn beheren.

Maatwerkcode heeft een duidelijke rol als een merchant een eigen omgeving voor medewerkers nodig heeft of een goedkeuringsproces dat meerdere interne systemen omvat. Revize biedt geen algemene API voor het bewerken van bestellingen en geen wachtrij waarin merchants bewerkingen goedkeuren.

Bureaus kunnen gedocumenteerde Shopify Flow-triggers koppelen aan bewerkingsgebeurtenissen van Revize, de bewerkings- en vrijgavetags van Revize gebruiken in hun fulfillment-logica of de Public Cancellation API gebruiken om annuleringen via een externe interface mogelijk te maken. De Public Cancellation API is alleen beschikbaar met Pro, moet door support worden ingeschakeld en volgt het bewerkingsvenster, de beperkingen en het terugbetalingsbeleid van het portaal.

Van de bewerkingen na aankoop bij winkels die Revize gebruiken, werd 92,2% door klanten afgerond zonder hulp van een medewerker van de klantenservice (Revize, 2026). De handleiding voor bureaus over bestellingen bewerken na aankoop behandelt wat je vóór de implementatie moet uitzoeken.

De beschikbaarheid van functies verschilt per abonnement. Producten toevoegen en omwisselen, terugbetalingen in winkeltegoed, herberekening van kortingen, verzending en belastingen, de regelengine, Reverse Unpaid Edits en de Public Cancellation API zijn alleen beschikbaar met Pro. Meer informatie staat in de documentatie over Revize-abonnementen.

Installeer Revize: Order Editing & Upsell als je klanten hun bestellingen zelf wilt laten aanpassen.

Hoe Revize de flow afrondt#

Revize biedt klanten een gecontroleerde bewerkingsflow op de Shopify-bestelstatuspagina. De merchant stelt het bewerkingsvenster, de beschikbare acties, het terugbetalingsbeleid en de verwerkingsmodus voor bestellingen in.

Als het totaal door een bewerking stijgt, toont Revize Pay now en stuurt de klant door naar de Shopify-checkout om alleen het verschil te betalen. Bij een lager totaal verschijnt Refund en bij een ongewijzigd totaal Confirm. Shopify voert de betaling of terugbetaling uit, zoals beschreven in de klantflow van Revize.

De merchant stelt de timing in onder Order Editing > Order edit window. De handleiding voor het instellen van het bewerkingsvenster beschrijft vaste opties, aangepaste looptijden, geplande sluitingstijden en de modus waarin bewerken mogelijk blijft tot fulfillment. Die laatste modus blokkeert een bestelling niet uit zichzelf.

In de aanbevolen verwerkingsmodus plaatst Revize tijdens het bewerkingsvenster een Shopify-blokkering op fulfillment en heft die op wanneer het venster sluit. Voor systemen die blokkeringen negeren, kan het gedocumenteerde alternatief met handmatige betalingsvastlegging nodig zijn. Een vrijgavetag kan ook als signaal dienen voor een fulfillment-systeem dat is ingesteld om op die tag te wachten.

Revize controleert de actuele voorraad voor de betreffende verzendzone voordat een klant een variant kan omwisselen. De handleiding over blokkeringen van fulfillment behandelt de magazijnkant van de flow.

Wat je deze week moet testen#

Test één bestelling van checkout tot correcte orderafhandeling, inclusief fouten. Een geslaagde mutatie in een GraphQL-client is pas het eerste controlepunt.

1. Maak een representatieve ontwikkel- of conceptbestelling aan.
2. Test een omwisseling zonder prijsverschil, een waardestijging en een waardedaling.
3. Controleer userErrors na de start, na elke mutatie die wijzigingen klaarzet en na de bevestiging.
4. Controleer de berekende bestelling voordat je bevestigt.
5. Controleer het innen van betalingen en de afhandeling van terugbetalingen afzonderlijk.
6. Stuur de bewerkte bestelling door het echte fulfillment-systeem.
7. Test een gearchiveerde bestelling, een oudere bestelling, overlappende bewerkingspogingen en een afgebroken bewerking.
8. Bekijk de beperkingen van Shopify’s eigen functies voor het bewerken van bestellingen voordat je toegang geeft in productie.