Shopify-voorraadverschillen verklaren en veilig corrigeren na een fysieke telling

Je kent het moment. De fysieke telling zegt 39 stuks, Shopify zegt 42, en intussen staat er een order in de pakstraat. De verleiding is groot om in Shopify gewoon drie stuks af te trekken. Daarmee corrigeer je misschien het scherm, maar nog niet de oorzaak, de financiële betekenis of de vraag of die drie stuks al in een andere beweging zitten.

Deze gids is voor Shopify-eigenaren en operationsmanagers die een voorraadverschil na een fysieke telling willen verklaren en gecontroleerd willen doorvoeren. Je eindigt met een dossier dat een tweede persoon kan beoordelen, een mutatie die niet over een gelijktijdige order heen schrijft en een boekhoudkundige vervolgstap die niet doet alsof Shopify je grootboek is.

Retouren, refunds en voorraadprognoses horen hier alleen als afbakening bij. Een retour per orderregel verwerken is een andere keten dan een telling, en een AI-voorraadprognose kijkt vooruit naar inkoop. Deze gids beantwoordt de smallere vraag: wanneer mag een voorraadcorrectie werkelijk schrijven?

Een Shopify-voorraadverschil is het verklaarde verschil tussen een fysieke telling en een gekozen Shopify-voorraadstatus op één locatie, op één afgesproken tijdstip. Je corrigeert pas nadat je pending ontvangsten, picks, transfers en andere mutaties uit dat telvenster hebt uitgesloten. De uiteindelijke vrijgave bevat een reden, bewijs, beslisser en technische sleutel.

Wat je nodig hebt voordat je telt

Begin niet in het Shopify-scherm. Begin met een afspraak over wat je precies gaat vergelijken. Shopify kent meerdere voorraadstatussen, locaties en bronnen die tegelijk kunnen schrijven. Een telling van alles wat fysiek in het gebouw ligt, is niet automatisch een telling van available voor verkoop.

1. Eén telobject en één bronhouder

Leg per telregel vast: SKU, variant, barcode, Shopify inventoryItemId, locatie, gekozen voorraadstatus, telwaarde en tijdstip. Kies bijvoorbeeld available als je wilt weten hoeveel stuks Shopify op dat moment mag verkopen. Tel je ook quarantaine, retouren of goederen in ontvangst, dan horen die in aparte staten en aparte regels. Meng ze niet in één getal.

Wijs daarna de bronhouder aan. Is je magazijnsysteem leidend voor aantallen en is Shopify alleen het verkoopkanaal, dan mag Shopify niet zomaar als waarheid worden behandeld. Shopify schrijft bij inventorySetQuantities zelf dat die mutatie bedoeld is voor een systeem dat bronhouder is voor voorraadhoeveelheden. In andere gevallen past inventoryAdjustQuantities beter. Die keuze en de kwartaalversies van de GraphQL Admin API heb ik op 8 oktober 2026 gecontroleerd in de Shopify-documentatie.

2. Een gesloten telvenster

Kies een begin- en eindtijd, bijvoorbeeld 8 oktober 2026 van 09:00 tot 10:00 uur. Noteer wie tijdens dat uur mag ontvangen, picken, verplaatsen of corrigeren. Het veiligste telvenster staat die handelingen kort stil. Lukt dat operationeel niet, maak dan een bewegingenlijst met:

• ontvangsten die al fysiek binnen zijn maar nog niet in Shopify staan;
• picks, pakketten en orders die wel fysiek bewegen maar nog niet in Shopify zijn verwerkt;
• transfers tussen locaties;
• voorraad die in quarantaine, reparatie of controle ligt;
• apps, WMS-systemen, Shopify POS en medewerkers die tegelijk kunnen schrijven.

Een pending beweging is geen ruis die je achteraf wel wegpoetst. Het is een verklaring die bepaalt of je een verschil werkelijk moet muteren. Dat past bij datasynchronisatie met één eigenaar per veld en een vaste reconciliatieronde. Shopify raadt voor webhookgestuurde koppelingen ook een periodieke reconciliatie aan, omdat aflevering en volgorde niet gegarandeerd zijn. Dat advies staat in de actuele webhookhandleiding, gecontroleerd op 8 oktober 2026.

3. Bewijs en rollen

Je hebt een telblad nodig dat de teller niet stiekem naar de Shopify-waarde laat kijken. Gebruik bij voorkeur een barcode-app of een CSV met alleen SKU en locatie. Laat een tweede persoon afwijkingen hertellen. Bewaar het originele telbestand, de export van Shopify vóór de telling, foto’s of notities bij uitzonderingen en de tijdstempels.

Splits vier rollen, ook als één persoon soms twee petten draagt:

• de teller stelt vast wat fysiek aanwezig is;
• operations verklaart pending bewegingen en kiest een interne oorzaakcode;
• een bevoegde reviewer geeft de voorgestelde mutatie vrij;
• finance beoordeelt de waardemutatie en de boeking.

4. Toegang tot Shopify en je boekhouding

Voor een geautomatiseerde route gebruik je de GraphQL Admin API met de actuele stabiele versie 2026-10 en de write_inventory-scope. De gebruiker of app moet ook Shopify-permissie hebben om voorraad te wijzigen. Zet de endpointversie expliciet in je configuratie, bijvoorbeeld /admin/api/2026-10/graphql.json, zodat een latere versie niet stilletjes je mutatie verandert.

Voor finance heb je de gekozen kostprijs per SKU nodig, de voorraadrekening, de rekening voor voorraadverschillen en de bevoegdheid om een boeking goed te keuren. Bij Moneybird is het belangrijk dat je het juiste object gebruikt. De actuele API-handleiding voor external_sales_invoices, laatst gewijzigd op 8 oktober 2026, gaat over omzet uit externe systemen en vraagt onder meer om een grootboekrekening en btw-code. Dat is geen bewijs dat een Shopify-voorraadcorrectie een verkoopfactuur moet worden. Gebruik de Moneybird-documentatie daarom als grens tussen omzetimport en je eigen voorraadboekingsroute.

5. Een mutatiedossier

Maak vóór de eerste vrijgave een tabel of database-record met minstens deze velden:

0/8

• SKU, variant, barcode, locatie en gekozen Shopify-status zijn vastgelegd
• Het telvenster en de toegestane bewegingen zijn bekend
• Een export van Shopify vóór de telling is opgeslagen
• Pending ontvangsten, picks, transfers en quarantaine hebben een eigenaar
• De teller ziet de Shopify-aantallen niet tijdens de eerste telling
• Interne oorzaakcodes, Shopify API-reason, kostprijs en goedkeuringsdrempels zijn afgesproken
• De Shopify-app heeft alleen de benodigde voorraadrechten
• Finance kan de voorraadwaarde en grootboekroute beoordelen

Concrete stappen: van fysieke telling naar veilige vrijgave

Met een veilige voorraadcorrectie breng je een fysieke telling, Shopify-snapshot en pending bewegingen samen tot één verklaarde delta. Je hertelt afwijkingen, classificeert de oorzaak, laat finance de waarde-impact beoordelen en laat een reviewer de Shopify-mutatie vrijgeven met idempotency key en controleerbare audittrail.

De controleerbare route bestaat uit deze negen stappen:

Stap 1: Maak de beginsnapshot en sluit je scope

Exporteer vlak voor de telling per SKU en locatie de gekozen status, de inventoryItemId, de actuele hoeveelheid en de tijd. Sla ook actieve transfers of ontvangsten op. Gebruik in een eenvoudige shop Shopify Admin en een CSV. Gebruik bij meerdere locaties een eigen stagingtabel, zodat iedere regel later terug te vinden is.

Maak daarna een telbestand met alleen wat de teller nodig heeft. Sorteer op magazijnlocatie, niet op verkooppopulariteit. Laat een nulwaarde ook expliciet tellen. Een ontbrekende regel betekent later niet automatisch nul.

Stap 2: Tel blind en hertel alleen wat afwijkt

De eerste telling is een waarneming, geen correctie. Scan of noteer de SKU, tel de fysieke verkoopbare eenheden en markeer eenheden die apart liggen. Tel dozen open als de verpakkingseenheid niet betrouwbaar is. Leg een beschadigd of onherkenbaar artikel op een uitzonderingsregel, niet bij de verkoopbare voorraad.

Vergelijk pas na het sluiten van het venster. Bij een verschil groter dan je afgesproken drempel volgt een tweede telling door iemand anders. Bij een afwijking van één stuk kan dat nog steeds nodig zijn als de kostprijs hoog is. Druk de drempel uit in stuks, euro’s en risico.

Stap 3: Reconcileer het telvenster voordat je een reden kiest

Zet de beginsnapshot, de fysieke telling en de pending bewegingen naast elkaar. Gebruik een eenvoudige controle:

verwachte eindstand = Shopify vóór telling + bevestigde systeembewegingen

Vergelijk daarna de fysieke verkoopbare voorraad met de verwachte eindstand. Een orderpick die nog niet is afgeboekt, verklaart een deel van het verschil. Een ontvangst die nog niet beschikbaar is, verklaart een ander deel. Een artikel in quarantaine kan fysiek aanwezig zijn, maar hoort niet in available.

Maak de bewegingen niet alsnog stilletjes groen. Laat iedere regel een status krijgen: verklaard, nog te verwerken, hertellen of onbekend. Alleen verklaard en nog te verwerken mogen door naar een voorgestelde correctie. Onbekend blijft geblokkeerd.

Stap 4: Classificeer de oorzaak en de financiële betekenis

Gebruik een vaste interne oorzaakcodeset. Dit veld is niet hetzelfde als Shopify’s API-reason. In het voorbeeld is de interne code shrinkage_after_recount; voor de Shopify-mutatie gebruik je de geldige API-reason correction. Stuur de interne oorzaakcode dus nooit als Shopify-enum mee.

Een onafhankelijke praktijknotitie van supply-chainconsultant Sébastien Mallevialle vat het risico scherp samen: een stocktake corrigeert het getal, maar niet vanzelf het proces dat het verschil veroorzaakte. Lees die praktijkanalyse, gepubliceerd op 8 september 2026 en gecontroleerd op 8 oktober 2026.

Gebruik minimaal deze zes codes:

Bereken de financiële impact met de goedgekeurde kostprijs, niet met de verkoopprijs. Twee ontbrekende stuks à € 24,50 betekenen in het voorbeeld € 49,00 lagere voorraadwaarde. De boeking hangt af van je waarderingsmethode en rekeningschema. De Belastingdienst beschrijft voorraad als een balanspost en noemt kostprijs als normale waardering; een lagere waardering is voor incourante goederen mogelijk onder de beschreven voorwaarden. Laat finance daarom de boeking en fiscale behandeling bepalen, gecontroleerd op 8 oktober 2026.

Een Shopify-mutatie en een financiële boeking zijn twee beslissingen. Een correctie van available kan een verkoopkanaal herstellen zonder dat er automatisch een journaalpost ontstaat. Andersom kan finance een verlies willen boeken terwijl operations eerst moet vaststellen of de stuks naar een andere locatie zijn verplaatst. Houd die besluiten gekoppeld, maar niet samengevoegd. Een webshopstatus is immers geen bewijs van een geslaagde geldbeweging.

Stap 5: Stage de mutatie, schrijf nog niets

Maak nu een voorstel met:

• de hoeveelheid vóór de mutatie;
• het verschil dat al door pending bewegingen wordt verklaard;
• de resterende delta;
• de interne oorzaakcode en de onderliggende bewijsregels;
• de Shopify API-reason voor de mutatie;
• de verwachte hoeveelheid na alle bewegingen;
• het financiële effect tegen kostprijs;
• de Shopify-locatie, inventoryItemId en voorraadstatus;
• de idempotency key en de interne Dossier-ID.

Toon de reviewer een leesbare samenvatting: “Shopify 42, fysiek 39, pending pick -1, voorgestelde correctie -2, na verwerking 39, interne oorzaakcode shrinkage_after_recount, Shopify API-reason correction, voorraadimpact € 49,00.” Een reviewer moet de uitkomst kunnen narekenen zonder GraphQL te lezen.

Stap 6: Kies de juiste Shopify-mutatie

Voor een gecontroleerde delta na een telling gebruik je normaal inventoryAdjustQuantities. Deze mutatie past een delta toe op een specifieke locatie, accepteert een reden en een referentie-URI en geeft een InventoryAdjustmentGroup terug met de uitgevoerde wijzigingen. Gebruik bijvoorbeeld API-reason correction en een referentie zoals stocktake://TELLING-2026-10-08-001. De interne oorzaakcode blijft in je dossier en wordt niet als Shopify-enum meegestuurd.

Shopify vermeldt voor de actuele 2026-10-referentie dat inventoryAdjustQuantities de write_inventory-scope vraagt. Vanaf versie 2026-04 is de idempotency key verplicht via @idempotent. De actuele mutatiedocumentatie noemt ook de reden, referentie-URI en auditgroep, gecontroleerd op 8 oktober 2026.

Gebruik inventorySetQuantities alleen als de bronhouder werkelijk absolute hoeveelheden beheert. Voeg dan de compare-and-set-bescherming toe: de mutatie mag alleen schrijven als de Shopify-waarde nog gelijk is aan de waarde die je hebt gelezen. Shopify waarschuwt dat het uitschakelen van die controle bij gelijktijdige verzoeken tot onjuiste aantallen kan leiden. Dat onderscheid staat in de actuele inventorySetQuantities-referentie, eveneens gecontroleerd op 8 oktober 2026.

Schrijf nooit een absolute waarde omdat die overzichtelijker lijkt. Als er tussen de snapshot en de vrijgave een nieuwe order is geplaatst, overschrijft een blind set die verkoopbeweging. Een delta met een actuele controle is in deze gids de veilige standaard.

Stap 7: Laat een mens vrijgeven

De reviewer controleert vijf dingen voordat de knop beschikbaar wordt:

1. de fysieke telling is volledig en een afwijking is herteld;
2. pending bewegingen zijn verwerkt, toegewezen of bewust afgetrokken;
3. de interne oorzaakcode past bij het bewijs;
4. de mutatie raakt de juiste SKU, locatie en voorraadstatus;
5. de financiële impact heeft een eigenaar en valt binnen het mandaat.

Blokkeer de vrijgave automatisch als de actuele Shopify-waarde niet meer overeenkomt met de snapshot, als een andere app na de telling heeft geschreven, als de telling meerdere locaties door elkaar haalt of als een boekingsrekening ontbreekt. De reviewer mag een voorstel afwijzen, terugsturen naar hertelling of vrijgeven met een toelichting. “Akkoord” zonder reden is geen audittrail.

Stap 8: Voer uit en controleer de uitkomst

Behandel een API-antwoord met userErrors als een blokkade. Sla de request, response, idempotency key, Shopify inventoryAdjustmentGroup, delta, interne oorzaakcode, Shopify API-reason, referentie-URI en tijdstip op. Haal daarna de voorraad opnieuw op. Controleer per regel:

• de nieuwe waarde is de verwachte waarde na pending bewegingen;
• de mutatie heeft de juiste locatie en status geraakt;
• er zijn geen GraphQL- of gebruikersfouten;
• de Dossier-ID staat in de referentie;
• de boekhoudkundige opvolging heeft een eigen status.

Krijg je na de call een time-out, markeer de uitkomst als unknown. Maak geen nieuwe idempotency key. Zoek eerst op je eigen dossier, de bestaande Shopify-adjustment en de opgeslagen sleutel. Shopify beschrijft idempotentie juist als bescherming tegen dubbele uitvoering bij een verstoorde verbinding. Een retry met dezelfde sleutel is herstel; een retry met een nieuwe sleutel is een nieuwe mutatie.

Stap 9: Sluit de financiële en operationele audittrail

De operationele afsluiting is pas klaar wanneer de nieuwe Shopify-stand klopt. De financiële afsluiting is pas klaar wanneer finance de waarde-impact, rekening, periode en eventuele boekings-ID heeft beoordeeld. Voeg beide resultaten aan hetzelfde dossier toe, met verschillende statussen.

Plan daarna een nachtelijke of wekelijkse controle die de gekozen Shopify-status opnieuw vergelijkt met je magazijnbron. Shopify’s eigen handleiding noemt updated_at-filters en periodieke reconciliatie als vangnet voor gemiste of verkeerd verwerkte webhooks. Gebruik zo’n controle om verschillen te signaleren, niet om ze blind te overschrijven. Een rood verschil is informatie. Dezelfde scheiding tussen operationele actie en financiële vrijgave zie je bij betalingen, payouts en gecontroleerde vrijgave.

Valkuilen die je telling onbetrouwbaar maken

Je telt terwijl de bron blijft schrijven

Een telling om 10:00 vergelijken met een Shopify-export van 08:00 zonder bewegingenlijst levert schijnprecisie op. Zet het telvenster dicht of log iedere ontvangst, pick en transfer met tijdstip en hoeveelheid.

Je vergelijkt available met alle fysieke spullen

Quarantaine, retouren, reparaties en gereserveerde goederen kunnen fysiek aanwezig zijn zonder verkoopbaar te zijn. Geef iedere voorraadstatus een eigen betekenis. Kies vooraf of je verkoopbare voorraad, on-hand of totale fysieke voorraad controleert.

Je gebruikt set om een onzeker verschil te verbergen

Een absolute mutatie maakt het scherm snel groen, maar kan een gelijktijdige order overschrijven. Gebruik bij een correctie een delta, of gebruik absolute waarden alleen vanuit een echte bronhouder met compare-and-set.

Je behandelt iedere afwijking als vermissing

Een verkeerd etiket, dubbele SKU, niet geboekte ontvangst of locatieverschil is geen shrinkage. Laat de reden pas kiezen na hertelling en bewegingenreplay. Zo voorkom je dat een procesfout als verlies in de boekhouding eindigt.

Je laat een time-out opnieuw uitvoeren met een nieuwe sleutel

De eerste mutatie kan al geslaagd zijn. Een nieuwe sleutel maakt van onzeker herstel een tweede mutatie. Zoek op Dossier-ID en idempotency key, leg de zoekactie vast en herhaal alleen veilig.

Je noemt Shopify-audit genoeg voor finance

Shopify kan vastleggen wie, wanneer en waarom een hoeveelheid veranderde. De helptekst zegt dat iedere aanpassing wordt geregistreerd en terug te vinden is in de geschiedenis, gecontroleerd op 8 oktober 2026. Dat bewijst nog niet welke kostprijs, rekening en periode in je administratie horen. Shopify’s voorraadgeschiedenis is het operationele bewijs; de boekings-ID is het financiële bewijs.

Je maakt van een voorraadcorrectie een verkoopfactuur

Een tekort van twee stuks is geen omzet en geen refund. De waarde-impact hoort thuis in de afgesproken voorraad- of verliesroute. In Moneybird is een externe verkoopfactuur bedoeld om omzet uit een ander systeem te importeren, niet om een ontbrekend magazijnstuk te maskeren.

Je vergeet multi-location

Een totaal kan gelijk lijken terwijl locatie A drie stuks te veel heeft en locatie B drie stuks te weinig. Shopify-mutations krijgen een specifieke locatie. Tel, stageer en reconcileer dus per locatie en verplaats niet via een correctie als het werkelijke probleem een transfer is.

Beslis-kader: wanneer welke route past

De beste route hangt af van vier dingen: aantal locaties, telfrequentie, financiële foutkosten en de vraag of een ander systeem bronhouder is. Een kleine shop met één magazijn kan prima met een blind telblad en Shopify Admin werken. Zodra je wekelijks telt, meerdere schrijvers hebt of finance op dezelfde vrijgave wacht, is een duurzame staginglaag geen luxe.

Vergelijkingstabel: handmatig, bulktool of maatwerk

Matrixify is sterk voor een eenmalige bulkbewerking en maakt de bestandsgrootte concreet. De eigen prijspagina noemt op 8 oktober 2026 een gratis demoplan, $20 voor Basic en $50 voor Big. Gebruik het als uitvoermiddel na je controle, niet als goedkeuringsproces. n8n is nuttig als orkestratielaag. De actuele Starter-prijs is €20 per maand bij jaarbetaling, met 2.500 volledige workflowuitvoeringen en onbeperkte stappen. Dat prijsmodel staat op de actuele n8n-prijspagina. Bewaar je dossier, sleutels en besluiten wel buiten een vluchtige workflowgeschiedenis.

Mijn beslisregel is streng: als een standaardtool alleen een getal kan schrijven, maar niet kan laten zien waarom dat getal klopt en wie het heeft vrijgegeven, is hij te klein voor je financiële voorraadproces. Gebruik hem dan hooguit voor export, import of meldingen.

Hoe groot is de teloperatie?

Eén locatie en hooguit enkele tellingen per jaarMeerdere locaties, wekelijkse tellingen of meerdere schrijvers

Uitgewerkt voorbeeld: twee ontbrekende stuks zonder dubbele correctie

Neem een Shopify-shop met één magazijnlocatie en het SKU MOKA-12-BLAUW. De voorraadbeheerder start op 8 oktober 2026 om 09:00 uur. Shopify toont voor available 42 stuks. De export bevat het inventoryItemId, de locatie en de tijd 09:00:12.

De teller vindt 39 verkoopbare stuks. Een hertelling door een tweede medewerker bevestigt 39. In het telvenster is één order gepickt, maar de WMS-webhook naar Shopify staat nog in de wachtrij. Die beweging verklaart dus één stuk. Na controle blijven twee stuks onverklaard. Een magazijnmedewerker vindt geen ontvangstbewijs, transfer of quarantainevoorraad. De interne oorzaakcode wordt shrinkage_after_recount. Dat is geen Shopify-API-enum: de mutatie krijgt later de geldige API-reason correction.

De staged regel ziet er zo uit:

De reviewer controleert de hertelling, het WMS-event, de twee incidentregels en de locatie. Finance bevestigt dat € 24,50 de actuele kostprijs is en bepaalt de voorraadverliesrekening. De correctie wordt nog niet als boeking vrijgegeven zolang dat rekeningbesluit ontbreekt.

Na goedkeuring voert de integratie inventoryAdjustQuantities uit op de juiste inventoryItemId en locatie, met delta -2, Shopify API-reason correction, referentie stocktake://TELLING-2026-10-08-001 en de verplichte idempotency key. De pending pick verwerkt daarna zijn eigen -1. De eindcontrole haalt Shopify opnieuw op en verwacht 39.

Stel dat de API-call een time-out geeft. Het dossier wordt unknown. De integratie zoekt op de interne sleutel en de Shopify-adjustmentgroep voordat er iets nieuws wordt gestuurd. Vindt zij de delta -2 al terug, dan slaat zij de herhaling over en koppelt zij de response aan het dossier. Vindt zij niets, dan herhaalt zij dezelfde mutatie met dezelfde idempotency key. Er kan geen tweede correctie ontstaan door paniek.

De financiële afsluiting bewaart naast de Shopify-response ook de boekings-ID, de toegepaste kostprijs, de rekening, de periode en de naam van de reviewer. De webshopstand is daarmee hersteld, het verlies is verklaard en een volgende medewerker kan de route teruglopen zonder de teller te bellen.

Wat je uiteindelijk vrijgeeft

Een voorraadcorrectie is geen knop maar een uitspraak: op dit tijdstip, op deze locatie, was dit de voorraad, dit is wat er fysiek is gecontroleerd, dit is wat er nog onderweg was en daarom mag deze delta worden geschreven. De techniek hoort die uitspraak te beschermen tegen dubbele events en gelijktijdige orders. De boekhouding hoort hem te vertalen naar waarde, rekening en periode.

De betrouwbaarste voorraadstand is daarom niet de stand die het snelst groen wordt. Het is de stand waarvan je nog kunt aanwijzen wie telde, welke bewegingen zijn uitgesloten, waarom het verschil bestaat en welke menselijke beslissing de mutatie heeft vrijgegeven. Als dat spoor intact blijft, wordt een telling geen jaarlijkse schoonmaakactie maar een controle die je dagelijkse operatie werkelijk beter maakt.