External stock writes

Product stock in Shopware can be changed by something outside the module: an integration with a warehouse system, an import, a script, another vendor’s plugin. Such a change does not take the shelves into account; it overwrites the number.

Stockly can notice it, react to it and record it for review.

Why it is a problem

The figure published to customers should follow from what is on the shelves. When it is written from outside, two values exist: one on the shelf and one on the product page. The difference is not visible immediately; it appears during picking, when the operator cannot find the goods, or as an oversell.

The reaction setting

Stockly → Settings → Stock → the General tab → the External stock writes section → the Reaction to external product stock writes field:

• Off — no detection. Writes through the API are absorbed as stock corrections, and direct database writes are silently overwritten by the next recalculation. This is the behaviour of the module until detection is switched on.
• Accept and correct shelves — the external figure wins: the difference is booked into the warehouse (into the unassigned bucket, or off the fullest bin) and the incident is recorded in the register.
• Reject and restore from shelves — the warehouse wins: nothing is booked, the field is rewritten from the shelves, and the rejected write is recorded in the register.

Caution

This setting decides which system is authoritative. If stock figures are deliberately owned by an external system, Accept is the right choice; if the warehouse is meant to be the authoritative source, Reject is. Choosing Off does not mean that nothing happens; it means that it happens without a record.

When a write is detected

• API writes — immediately.
• Direct database writes — at the product’s next stock event, which is exactly the moment the module would otherwise overwrite them.

The mechanism targets a misconfigured integration, not deliberate tampering with the database.

Note

There is one known exception: deleting a warehouse recomputes the figure for every affected product at once. A foreign write sitting there at that moment is overwritten without an entry in the register, so the net effect is the same as Reject, except that the trace is missing.

The incident register

Stockly → Warehouses → External writes (an entry in the warehouse section rail).

Columns: Detected, Product, Expected, Found, Difference, Source, Reaction, User.

Expected is the figure the shelves add up to, Found the one somebody wrote; Difference shows the drift.

Source distinguishes:

Value	Meaning
API write	a write through the API or the admin
Direct database write	a write straight into the database, bypassing the shop

Reaction says what the module did about it:

Value	Meaning
Accepted, shelves corrected	the external figure was taken and the shelves corrected
Rejected, value restored	the write was rejected and the value restored from the shelves

The list can be filtered by source, reaction and detection date.

An empty register means nobody wrote stock from outside while detection was on.

A correction booked under the Accept reaction also stays in the movement history, with the reason Stock corrected after an external change: the register records the external write, and the history records the module’s reaction. → Movement history

The summary notification

The Daily summary notification switch in the same section raises one admin notification per day when new incidents were recorded since the previous summary — never one per event.

A scheduled task takes care of it. → Scheduled tasks

Reacting in a shop’s own process

Every detected write raises an event available in Flow Builder, carrying the product, the expected value, the found value, the difference, the source and the reaction applied. It can drive a notification of the shop’s own, an entry in an external system, or an alert for IT.

How it relates to the integrity check

These are two moments of the same subject:

• External stock writes work live: they catch the change as it happens and settle it straight away.
• The integrity check and the repair wizard clean up after the fact, once the drift already exists, for instance because detection was off.

If the repair wizard keeps showing the same group of findings about the published figure against the shelf, detection should be switched on and the problem settled at its source instead of being repaired every week.

For developers: the detection mechanism, the event payload and the incident entity are described in external writes.