What a magento dynamics 365 integration is actually synchronising

The first question in any magento dynamics 365 integration is not which API to call. It is which number, out of the six or seven that each system holds, is the one a customer should be allowed to buy against. Teams who skip this question tend to build a working pipeline that delivers the wrong figure very reliably, and then spend months adding exceptions to it.

Microsoft Dynamics 365 holds several distinct quantities for the same item at the same warehouse. Physical on-hand is what has been received and not yet issued. Physical reserved is the portion committed to open sales or transfer lines. Ordered quantity covers goods on inbound purchase orders that have not arrived. Available physical, broadly, is on-hand less reserved less picked. Each of these is legitimate; each answers a different business question. A distributor promising same-day despatch cares about available physical at one site. A brand selling a pre-order run cares about ordered quantity with an expected receipt date attached.

Magento, since the introduction of Multi-Source Inventory, splits the picture differently. Source items carry a quantity and a status per source. A stock aggregates one or more sources and is assigned to a website. On top of that sits salable quantity, which is the aggregated source quantity minus Magento's own reservations for orders that have been placed but not yet shipped. The storefront shows salable quantity. That distinction matters more than anything else in this build, and it is the subject of the reservations section below.

Before any code is written, the mapping should be agreed in writing: which Dynamics 365 sites and warehouses correspond to which Magento sources, which quantity field feeds the source item quantity, and what happens to items that exist in one system and not the other. This is ordinary discovery work and it is quicker to do on paper than to discover from a variance report three weeks after go-live.

Deciding the figure that goes on the shelf edge

Once the fields are understood, the available-to-promise calculation can be written down as an explicit formula rather than left implicit in code. For most single-warehouse operations the starting point is available physical at the nominated warehouse, floored at zero, with a buffer subtracted for items where the count is known to drift. For multi-site operations the formula needs a rule about which sites are sellable online at all: bonded stock, quarantine locations, customer-owned consignment and goods in transit are frequently included in a naive on-hand query and should not be.

Two refinements are worth agreeing up front. The first is the treatment of stock that is physically present but blocked — inventory status in Dynamics 365 can mark quantities as unavailable, and a query that ignores status will oversell. The second is the handling of items with no record at all in the warehouse: an item that has never been received returns nothing rather than zero, and an integration that only writes rows it receives will leave the previous quantity in place indefinitely. The safe pattern is to derive the expected item set from the Magento catalogue, then treat a missing Dynamics 365 result as an explicit zero.

It is also worth deciding what the storefront does when the figure reaches zero. Magento can be configured to allow backorders at the source item level, and that flag is part of the sync payload, not a static setting. If the commercial rule is that A-lines never go out of stock but seasonal lines do, that rule has to live somewhere in the mapping and be visible to whoever maintains it later.

  • Available physical — The usual base figure from Dynamics 365: on-hand less reserved less picked, taken at warehouse level rather than across all sites.
  • Inventory status filter — Exclude quantities held under a blocked or quarantine status, otherwise the storefront will sell goods the warehouse cannot release.
  • Buffer — A per-item or per-category deduction covering count drift and pick errors. Keep it as data, not a hard-coded constant.
  • Zero-fill rule — Any catalogue item with no matching on-hand record is written as zero rather than skipped, so discontinued lines fall out of sale.

Cadence, deltas and the cost of pushing everything

A full push of every item on every cycle is attractive because it is simple and self-healing. It is also the fastest way to exhaust API capacity on both sides. Dynamics 365 applies priority-based throttling to OData and custom service calls, and a naive loop over ten thousand items will be slowed or rejected well before it finishes. Magento's REST endpoints will accept source item updates in batches, and the asynchronous bulk endpoints will queue them, but every queued message still has to be consumed by a cron-driven consumer and every stock write triggers reindexing work.

A workable pattern for most mid-sized catalogues is a two-tier cadence. Incremental updates run every few minutes and carry only items whose on-hand figure has changed since the last successful run, identified either by a modified-date filter on the relevant data entity with change tracking enabled, or by business events raised from Dynamics 365 onto a queue that the middleware consumes. A full reconciliation pass runs overnight, outside trading hours, and writes the complete set. The incremental tier keeps the storefront honest during the day; the nightly pass corrects anything the incremental tier missed.

Batch sizes should be tuned rather than guessed. Writing source items in blocks of one to two hundred, with a bounded concurrency of two or three workers, is usually a sensible starting point on Magento; the limiting factor tends to be indexer throughput rather than HTTP. On the Dynamics 365 side, $batch requests reduce round trips considerably, but a single oversized batch that fails takes everything in it down with it, so batches should be sized so that a retry is cheap.

Every run needs a recorded high-water mark and an idempotent write. Stock quantities are naturally idempotent — writing the same figure twice causes no harm — which makes this one of the few integrations where at-least-once delivery is comfortable. Take advantage of that: on any ambiguous failure, retry rather than attempt to work out whether the write landed.

Reservations and the double-decrement trap

This is where most builds go wrong, and it is worth describing precisely. A customer places an order on Magento. Magento immediately creates a reservation, which reduces salable quantity while leaving the underlying source item quantity untouched. The order is passed to Dynamics 365, where a sales line is created and stock is reserved against it, reducing available physical. Nothing has shipped, so the physical on-hand figure has not moved in either system.

Now the stock sync runs. It reads available physical from Dynamics 365 — already reduced by the reservation — and writes it to the Magento source item. Magento then subtracts its own reservation from that figure to produce salable quantity. The same order has been deducted twice, and the storefront now shows one fewer unit than it should. On a fast-moving line with several orders an hour, that error compounds until the item shows as out of stock while pallets of it sit in the warehouse.

There are two defensible resolutions and they should not be mixed. The first is to sync physical on-hand from Dynamics 365, unreduced by reservations, and to let Magento's own reservation mechanism handle the deduction for orders it originated. This works cleanly when Magento is the only sales channel and all demand flows through it. The second is to sync available physical from Dynamics 365 and to clear the Magento reservation as soon as the order is acknowledged by the ERP, so that only one system is holding the commitment at any moment. This is the correct choice when the same stock pool serves trade orders, marketplaces or telephone sales entered directly into Dynamics 365.

Whichever is chosen, the reservation lifecycle needs to be traced end to end during acceptance testing: order placed, order acknowledged, order picked, order despatched, order cancelled, order partially shipped, order refunded. Cancellation and partial shipment are the two cases that most often leave an orphaned reservation behind, and orphaned reservations in Magento are invisible on the product page — they simply make the salable quantity quietly wrong.

The edge cases that actually cause tickets

Unit of measure is the first. Dynamics 365 maintains an inventory unit per item and may transact in cases, pallets or metres while the storefront sells eaches. If the conversion is not applied in the integration, an item held as twelve cases will appear on the website as twelve units. Conversions should be read from Dynamics 365 rather than maintained separately in mapping tables, because a product manager changing a case size in the ERP will not think to tell anyone about a spreadsheet.

Composite products are the second. Magento bundle and grouped products, and configurable products with child simples, each behave differently in the salable quantity calculation. A bundle's availability is derived from its components, so writing a quantity directly against the bundle SKU achieves nothing. Where Dynamics 365 holds a kit or bill of materials that is assembled to order, the sellable figure has to be computed as the minimum assembly quantity across components, and that computation belongs in the middleware where it can be tested, not in a stored procedure nobody will find later.

Third, a warehouse management layer often sits between the two. Where Peoplevox or Mintsoft is running the pick and pack operation, the live count is in the WMS and Dynamics 365 is updated on a lagging basis through goods issue postings. Syncing the storefront from the ERP in that situation means selling against a figure that may be several hours stale. The usual answer is to take the quantity from the WMS and the item master, pricing and costing from the ERP, and to reconcile the two nightly. That is a design decision with cost implications, and it needs to be made during discovery rather than discovered during build.

Finally, returns and stock adjustments. A returned item that has been received but not yet inspected should not normally be sellable, and cycle-count adjustments posted in Dynamics 365 can move a quantity sharply in either direction. Both are legitimate movements that the incremental sync will pick up; the point is that operations staff should be able to see why a figure changed. A movement log keyed by SKU, timestamp, source system and resulting quantity answers ninety per cent of the questions that would otherwise arrive as support tickets.

Proving it works, and keeping it working

Acceptance testing for stock sync should be quantitative. The test is not that the pipeline ran without errors; it is that for a defined sample of SKUs, at a defined moment, the Magento salable quantity equals the expected figure derived from Dynamics 365 under the agreed formula. Run that comparison across the full catalogue, not a sample, at least once before go-live, and record the variances and their causes. Every unexplained variance at that point is a defect that will recur in production.

In steady state, a daily reconciliation report is the single most valuable artefact this integration produces. It lists every SKU where the two systems disagree by more than an agreed tolerance, with both figures and the timestamp of the last successful write. A short list that is reviewed each morning keeps small problems small. A report nobody reads is worse than no report, so agree who owns it before handover.

Alerting should be separated from reporting. The conditions worth waking someone for are narrow: the sync has not completed successfully within its expected window, the error rate on writes has exceeded a threshold, or the number of items moving to zero in a single run has exceeded a sensible bound. That last one is the guard against a bad query returning empty results and silently zeroing the catalogue, which is the most damaging failure mode this integration has.

Handover should include the mapping document, the available-to-promise formula in plain English alongside the code that implements it, the run book for the common failure cases, and the credentials and endpoint configuration in a form the client can change without calling anyone. The integration will outlive the project. It should be legible to whoever inherits it, which in our experience is rarely the person who commissioned it.

Key points

  • Agree in writing which Dynamics 365 quantity feeds the storefront, and whether Magento reservations or ERP reservations own the deduction — never both.
  • Run incremental updates through the trading day and a full reconciliation pass overnight, with batch sizes tuned to Magento's indexers and Dynamics 365 throttling.
  • Test against the full catalogue before go-live and keep a daily variance report with a guard against any run that zeroes an unexpected number of items.