=== Stock Alibi – Stock & Price Change Log for WooCommerce ===
Contributors: archimidism
Tags: woocommerce, stock, inventory, price history, audit log
Requires at least: 6.9
Tested up to: 7.1
Requires PHP: 8.1
Stable tag: 1.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

See who and what changed every stock level and price in WooCommerce: orders, refunds, admins, API, imports and ERP syncs.

== Description ==

**Every stock and price change has an alibi.**

It is Monday morning and a best-seller shows 0 in stock. The warehouse says there are 14. Was it last night's ERP sync? An order that was cancelled? A colleague with Quick Edit? A CSV import? WooCommerce keeps no history of product changes, so the honest answer is usually "we don't know".

Stock Alibi records every change to the stock and prices of your products and variations **together with its source**, and explains it in a sentence:

> Stock: 12 → 14. REST API request PUT /wc/v3/products/batch. Application password "SoftOne ERP". 14 minutes after order #23, which had changed the stock from 14 to 12.

> Regular price: 54 → 49. Changed directly in the database, sometime between 3:15 pm and 3:30 pm.

> Refund #1085 of order #1083 returned the items to stock.

= A source for every change, not only for orders =

Most logs get orders right and file everything else under "purchase" or "third-party system". Stock Alibi names each one:

* **Orders**: the order that reduced the stock, the cancelled or failed order that put it back, the refund that restocked items (with the refund number), and edits of an order's items in the admin.
* **People**: the product screen, Quick Edit, Bulk Edit and the variation bulk actions, with the user who made the change.
* **Integrations**: the REST API with its route and the WooCommerce API key (description and last characters only) or the application password; CSV imports with the file name; WP-CLI with the command; WP-Cron and Action Scheduler tasks with their hook.
* **Scheduled sales** starting and ending, including the active price.
* **Other plugins and themes**, by name.
* **Writes around WooCommerce**: code that writes product data straight to the database meta (`update_post_meta`) instead of using WooCommerce.
* **Direct database changes**: an ERP or script that runs SQL fires no hook at all. A background check compares the database with the recorded history and records what nothing explains, with the time window in which it happened.

When the source cannot be determined, Stock Alibi says "unknown". It never guesses: a wrong answer is worse than an honest "we don't know".

= What it records =

Stock quantity, stock status, manage stock and backorders; regular price, sale price, sale dates and the active price; the initial values of new products. For each change: old and new value, source, reference (order number, REST route, file name, plugin), user, time, and an ID that groups everything one request changed. Variable products are recorded per variation, and a parent's synced stock status gets the source of the variation change that caused it.

= What you see =

* **Product history**: a "Stock & price history" box on every product screen, with a plain-language summary and the latest changes of the product and its variations, grouped by request.
* **History**: every change, with filters by product, field, source, dates, order, SKU or reference. Every view is a link you can bookmark or send.
* **Report**: changes by source, by day and by product, for example "43% of the stock changes came from the REST API".
* **Anomalies**: stock below zero without backorders, an order item that reduced the stock twice, an automated sync that overwrote the stock right after sales, and prices changed outside WooCommerce. Each links to the orders and changes that prove it.
* **CSV export** of the history, report and anomalies, with the same filters.

Ready for translation on translate.wordpress.org.

= Built for stores with integrations =

Stock Alibi is made for stores connected to an ERP, a POS, marketplaces or imports, and for the developers and agencies who support them. It answers "is the bridge wrong, or was it the import on Tuesday?" with evidence instead of opinions.

= Read-only and light =

Stock Alibi only reads: it never changes products, orders or stock. At checkout it adds one small indexed query per order line and writes the request's changes in one query at the end. In tests a four-line checkout took the same time with and without it. The database check runs in Action Scheduler, in batches, never on the storefront (60,000 products checked in about 9 seconds). Old changes are deleted after a retention period you choose (180 days by default).

= AI-ready, never AI-required =

On WordPress 6.9 and newer the history is available as five read-only abilities: explain a change, product history, search, store report and anomalies. With the WordPress MCP Adapter plugin, an AI assistant such as Claude or ChatGPT can answer "why did the stock of this SKU drop to 0 yesterday?" from the recorded facts, not from a guess. If the site has an AI provider set up in WordPress, the product screen also offers an "Explain with AI" button. Everything works without AI.

= Privacy =

No external requests, no telemetry. The history stores user IDs and order numbers, never names, addresses or payment details. Stock Alibi adds a suggested text to your privacy policy and works with WordPress's personal data export and erasure tools.

= For developers =

* Name your integration with the `stock_alibi_resolve_source` filter, so its changes show as "SoftOne" instead of "REST API".
* Receive every batch of recorded changes with the `stock_alibi_events_recorded` action.
* Requires WooCommerce 10.0 or newer. Compatible with High-Performance Order Storage and the Cart and Checkout blocks.

== Installation ==

1. Install and activate WooCommerce 10.0 or newer.
2. Install Stock Alibi from the Plugins screen, or upload the `stock-alibi` folder to `/wp-content/plugins/`, and activate it.
3. Stock Alibi starts recording right away. There is nothing to set up.
4. See the history of a product in the "Stock & price history" box of the product screen, and everything else under WooCommerce › Stock Alibi.
5. Optionally, adjust the retention period and how often to look for direct database changes under WooCommerce › Stock Alibi › Settings.

Changes made before Stock Alibi was activated, or while it was inactive, are not in the history.

== Frequently Asked Questions ==

= Does Stock Alibi change my stock or prices? =

No. Stock Alibi only reads. It never changes products, orders or stock.

= Will it slow down my checkout? =

No noticeable difference. At checkout Stock Alibi reads the current stock of each order line before WooCommerce changes it (one small indexed query per line) and writes all the changes of the request in one query at the end. In our tests a checkout of four lines took the same time with and without the plugin; the plugin's own queries took about 2 ms.

= Does it work with large catalogs? =

Yes. The background check reads products in batches of 500 directly from the database: in our tests, a catalog of 60,000 products and variations was checked in about 9 seconds, in Action Scheduler. The screens were tested with a history of one million changes.

= How does it find changes made directly in the database? =

Some ERP connectors and scripts write stock and prices with SQL, which WordPress and WooCommerce never see. Every 15 minutes (adjustable, or off) Stock Alibi compares the stored values with what its history explains. A value that nothing explains, and that is still there five minutes later, is recorded as a "Direct database change", with the time window in which it happened.

= My ERP connector shows as "REST API". Can it show its own name? =

Yes, with the `stock_alibi_resolve_source` filter:

`add_filter( 'stock_alibi_resolve_source', function ( $result, $product_id, $parent_id ) {
	if ( 'rest' === $result['source'] && str_contains( $result['ref'], '/erp/' ) ) {
		$result['source'] = 'softone';
		$result['ref']    = 'nightly sync';
	}
	return $result;
}, 10, 3 );`

Order sources (order, cancellation, refund) are always kept, and direct database changes cannot be renamed, because nobody can know who made them.

= Who can see the history? =

Users who can manage WooCommerce (shop managers and administrators). The same applies to the abilities.

= Does it work with variable products? =

Yes. Stock and prices are recorded on each variation. When a variation's stock changes the stock status of its parent, the parent's change gets the same source.

= What about privacy and the GDPR? =

The history stores the user ID with changes made by logged-in users (for example a customer whose order reduced the stock), and order numbers. It stores no names, email addresses, postal addresses or payment details. Stock Alibi adds a suggested text to Settings › Privacy, and works with Tools › Export Personal Data and Erase Personal Data: an erasure removes the user ID from the changes and keeps the stock history itself.

= Does Stock Alibi send data anywhere? =

No. Stock Alibi makes no external requests and has no telemetry. If the site owner has set up an AI provider in WordPress (Settings › Connectors, WordPress 7.0 or newer), the product screen shows an "Explain with AI" button; only when it is clicked, WordPress sends that product's recorded changes of the last 90 days (fields, values, sources, order numbers; no user names or customer details) to that provider. Stock Alibi stores no API key.

= Does it work with AI assistants? =

Yes, optionally. On WordPress 6.9 or newer, the history is available as five read-only abilities for users who can manage WooCommerce. With the WordPress MCP Adapter plugin, MCP clients can use them. Nothing of this is needed to use the plugin.

= What happens to the data when I delete the plugin? =

It stays, unless you enable "Delete the change log and all plugin settings when the plugin is deleted" under WooCommerce › Stock Alibi › Settings. Deactivating the plugin stops recording and the background jobs, and keeps the data.

== Screenshots ==

1. The "Stock & price history" box on the product screen: a plain-language summary and the latest changes, grouped by request.
2. History: every change with its source and explanation, with filters.
3. Report: changes by source, by day and by product.
4. Anomalies, with links to the orders and to the changes that prove each one.
5. Settings: retention and how often to look for direct database changes.

== Changelog ==

= 1.0.0 =
* First public release.
* Records every change to stock (quantity, status, manage stock, backorders) and prices (regular, sale, sale dates, active price) of products and variations, with its source: orders, cancellations, failed payments, refunds, order edits, the product screen, Quick Edit, Bulk Edit, the REST API (route, API key or application password), CSV imports, WP-CLI, WP-Cron, Action Scheduler, scheduled sales, other plugins and themes, direct meta writes and direct database changes.
* Product history box, History, Report and Anomalies screens, CSV export, plain-language explanations.
* Read-only abilities for the WordPress Abilities API and MCP clients; optional "Explain with AI" when the site has an AI provider.
* Privacy: suggested policy text, personal data export and erasure.
