Kitgenix Stock Sync for WooCommerce

Kitgenix Stock Sync for WooCommerce synchronizes inventory between WooCommerce stores using a Master/Child architecture. The Master store acts as the authoritative inventory source while Child stores send stock-changing events back to the Master and receive the resulting authoritative stock state.

The plugin is built for merchants who sell the same physical inventory through several WooCommerce storefronts and need stock quantity, stock status and backorder behaviour to converge without manually exporting or importing inventory files.

Stores communicate directly over signed REST requests; there is no Kitgenix cloud stock relay. Background delivery uses WooCommerce Action Scheduler where available, with retries and backlog handling for temporary failures.

Key capabilities include one Master store with one or more Child stores, SKU and global-ID based matching, synchronization of stock quantity, status, backorders and low-stock amount, asynchronous event delivery with retries and duplicate-event protection, conflict scanning and reconciliation, a Stock History log per SKU, a SKU Mapping Repair Tool, a Failover Readiness Report, strict checkout validation, shared-secret rotation, signed REST authentication, Site Health integration and WP-CLI tooling.

See the Other Notes section below for full details on each feature area, and the FAQ for common questions.

WooCommerce Stock Sync Features

• One authoritative Master store with one or more Child stores.
• SKU-based product/variation matching plus plugin global IDs for stable identity.
• Synchronization of stock quantity, status, backorder setting and low-stock amount.
• Effective stock-management mode handling, including variation inheritance from a parent product.
• Automatic capture of WooCommerce stock-change hooks, order processing and stock restoration.
• Asynchronous event delivery with retries/backoff, per-event versioning and duplicate-event detection.
• Persistent backlog for recoverable failed deliveries.
• Conflict scanning and reconciliation tools.
• Stock History per SKU: versioned stock events for one product across connected stores.
• SKU Mapping Repair Tool: find and fix duplicate or missing SKU identities, with sync held for ambiguous SKUs until they are repaired.
• Failover Readiness Report: what happens if the Master is unreachable, including the age of last-known-good stock snapshots.
• Strict Child-store checkout validation option, with cached-snapshot/failure strategy options.
• SKU rename tracking and product/SKU exclusions.
• Shared-secret rotation, signed REST authentication and replay protection.
• Scheduled health checks, connection status and WordPress Site Health integration.
• Event log, diagnostic code reference and WP-CLI tooling.
• WooCommerce HPOS compatibility handling.

Master and Child Architecture

The Master owns the authoritative stock state. A Child store can detect a local event that changes stock, send that event to the Master, and then receive the authoritative result that should be applied across the network.

This avoids a simple “last store to save wins” design in which two storefronts can continually overwrite one another with stale quantities.

The Master configuration stores the connected Child sites and the Child configuration stores the Master endpoint/credentials needed for signed communication.

Inventory Fields Synchronized

The state payload includes the stock-related fields needed to keep WooCommerce availability consistent, including quantity, status, backorders, low-stock amount and effective manage-stock state.

Variable products/variations are handled with awareness that a variation may manage its own stock or inherit stock management from the parent product.

The plugin focuses on stock. It is not a general product-catalogue synchronizer for descriptions, images, categories and full pricing; Kitgenix MultiStore Sync is a separate broader plugin for that use case.

Automatic Capture of Stock Changes

The sync engine hooks into WooCommerce product/variation stock updates, stock-status updates, updated product properties, order processing and stock restoration. This means stock changes made by normal WooCommerce operations can enter the sync pipeline without staff having to click a separate “export stock” button.

Because third-party integrations such as POS or marketplace connectors often write stock through WooCommerce’s normal APIs/hooks, their resulting WooCommerce stock changes can also be observed without the Kitgenix plugin calling the third party directly.

Event Versioning and Duplicate Protection

Each synchronized product carries plugin metadata used for global identity and event versioning. The receiver tracks the applied version so an older delayed event can be rejected instead of rolling stock backwards after a newer update has already been applied.

Event IDs are also remembered for a limited period so a duplicated/retried delivery is not applied as though it were a brand-new inventory movement.

Retry and Backlog Handling

Outbound failures are classified and retried using increasing delays. Recoverable failures can be persisted in a capped backlog so administrators can see that inventory delivery is pending rather than assuming a silent request succeeded.

Backlog entries can be retried or discarded from the administrative tools when appropriate. Successful later delivery removes the corresponding outstanding item.

Reconciliation and Conflict Detection

The Master can scan Child stores and compare their current stock state with the authoritative record. Reconciliation processes products in batches and can continue through Action Scheduler rather than requiring a single long-running browser request.

Conflict reports can identify mismatched stock or duplicate-SKU conditions that need manual attention. The plugin also exposes audit/reconciliation functionality through WP-CLI.

Strict Checkout Validation

A Child store can optionally validate cart quantities against the Master during checkout. This is intended to reduce overselling when the local storefront’s last synchronized value is older than the authoritative stock.

Because the Master can be temporarily unreachable, the plugin includes configurable behaviour around failure and stale cached stock snapshots. Stores should choose a strategy that matches whether they prefer checkout availability or strict oversell prevention during network outages.

SKU Rename Handling

The plugin observes SKU metadata changes so identity can remain consistent when a product’s SKU is edited. Global plugin IDs provide another stable identifier used by the sync process, reducing dependence on the assumption that a SKU can never change.

Stock History per SKU

Each store keeps a short, versioned history of stock events for every product it syncs: local changes captured on a Child, authoritative versions stamped by the Master, updates applied on each store, SKU renames, and stale updates that were safely ignored. Every entry records the stock quantity, stock status, backorder setting, version, context (for example an order or a reconcile), the originating store, and the event ID.

Look up a SKU on the Tools tab to see its current state on every connected store side by side, plus one merged timeline. Entries with the same event ID are the same change seen on different stores, so you can follow a sale from the store where it happened, through the Master, to every Child that applied it. The Master shows every enabled Child; a Child shows itself and the Master. The same lookup is available from WP-CLI.

SKU Mapping Repair Tool

Sync matches products between stores by a plugin GID and by SKU, so both must identify exactly one product. The SKU Mapping Repair Tool (Conflicts tab) scans a store for:

• Duplicate SKUs – one SKU used by more than one product or variation.
• Duplicate GIDs – one GID shared by more than one product, usually left behind by a product duplicate or import that copied product meta.
• Missing SKUs – stock-managed products and variations with no SKU, which can never sync.

Duplicate SKUs and duplicate GIDs are put on a sync hold: the SKU is skipped by every inbound and outbound sync path until it is repaired, so an ambiguous match can never overwrite the wrong product’s stock. Repair from the same screen by assigning a unique SKU or issuing a new GID. Holds are released automatically once the identity is unique again, and on the Master the released SKUs are pushed to every Child so sync resumes. A hold can also be released manually.

On the Master, the tool also lists GID mismatches and missing products found on Child stores by the latest Audit or Reconcile, with a one-click push that makes the Child adopt the Master’s GID.

Failover Readiness Report

The Status tab includes a Failover Readiness Report that explains, from the store’s live settings and health, what happens if the Master is unreachable: whether customers can still check out, how long queued stock changes keep retrying before they need attention, how stock drifts while stores are disconnected, how many last-known-good stock snapshots are stored and how old they are, and the steps to recover – including promoting a Child to Master. Each finding is graded and the report gives an overall verdict (Ready, At risk, Not ready).

On the Master, the report also lists every Child’s checkout fallback, snapshot freshness and backlog, reported by each Child during the regular health ping. The report can be downloaded as a Markdown file or printed with WP-CLI.

Exclusions

Administrators can exclude specific SKUs from stock synchronization. Excluded products are ignored by normal event delivery and reconciliation so local-only inventory is not continually overwritten.

Secure Signed REST Requests

Master and Child REST requests are signed using the shared-secret authentication layer. Requests include timing/identity information and are rejected when they are invalid, too large, outside the accepted window or fail replay/authentication checks.

The security layer also contains throttling/temporary lockout behaviour for repeated authentication failures and remote URL validation.

Shared secrets can be rotated with a configured overlap period so a network can move from an old secret to a new one without requiring every in-flight request to fail at the exact rotation second.

Health Monitoring

Scheduled health pings update the stored connection status for the Master/Child relationship. The admin interface and Site Health integration can report configuration, connectivity, backlog and Action Scheduler concerns.

WP-CLI

The command base is:

wp kitgenix-stock-sync

The command class includes status, audit/reconciliation, SKU-level actions, backlog/conflict tooling and formatting helpers for operational use from the command line.

Direct Store-to-Store Data Flow

Stock events and stock-state queries are sent only between the WooCommerce sites configured by the administrator. Kitgenix does not receive the store’s inventory feed or act as a remote source of truth.

The shared Kitgenix admin Hub can separately request public plugin metadata from WordPress.org, and the admin stylesheet imports Google Fonts as documented in External Services. Those requests do not contain WooCommerce stock payloads.

Typical Uses

• Separate retail and wholesale WooCommerce stores sharing one warehouse quantity.
• UK and Ireland storefronts selling from the same physical stock pool.
• Brand/domain-specific stores that must not oversell shared inventory.
• A POS/integration updating the Master while web storefronts follow the authoritative result.
• Stores that need backorder and stock-status behaviour kept consistent as well as the numeric quantity.

External Services

This is a store-to-store sync plugin, so connecting to remote services is core to how it works. It talks to two kinds of external endpoint:

1. Your own WooCommerce stores (Master and Child)

The plugin makes signed REST API requests directly between the WordPress/WooCommerce sites you configure as Master and Child – it does not route data through any Kitgenix server or third-party service. Master and Child URLs must use HTTPS (a filter allows plain http:// only for localhost/.local/.test hosts for local development).

• What is sent: product SKUs; stock state (quantity, stock status, backorders, low stock amount, effective stock-management mode); a per-product monotonic version counter and timestamp (see How Stock Sync Works); and, only via the /ping health-check route, the sending store’s name and its WooCommerce/plugin version. Strict checkout validation additionally sends the SKUs currently in a Child’s cart to the Master for a live stock check.
• When it happens: automatically, in real time, whenever WooCommerce itself changes a product’s stock (an order, refund, cancellation, REST edit, CSV import, or a compatible integration such as WooCommerce Square) – dispatched asynchronously via Action Scheduler. There is no polling interval to configure. A recurring health-check ping additionally runs roughly every 15 minutes per configured store, and Reconcile/Audit/Manual SKU Sync send requests on demand when you trigger them.
• Authentication: every request carries X-Kitgenix-Store-Id, X-Kitgenix-Timestamp, X-Kitgenix-Nonce, and HMAC-SHA256 X-Kitgenix-Signature / X-Kitgenix-Signature-V2 headers computed from a shared secret you configure on both sides – see Developer Reference below for the full scheme.
• Caching: a last-known-good stock snapshot per SKU is cached (transient, 24 hours) on Child stores solely to support the optional “use last-known stock” checkout failure strategy; a GID → product ID lookup is cached in the object cache (~1 hour) if a persistent object cache is active.

2. WordPress.org Plugins API (admin screen only, not part of stock sync)

The plugin includes a shared “Kitgenix hub” admin page (Kitgenix → top-level menu) listing other Kitgenix plugins. To populate install counts, ratings, and artwork for plugins listed there, it calls WordPress core’s own plugins_api() function, which requests public plugin metadata from api.wordpress.org. No site data, settings, or stock information is sent in these requests – only the public plugin slugs of the Kitgenix plugins shown on that page.

• Cached via transients: kitgenix_hub_wporg_active_installs_v1, kitgenix_hub_wporg_ratings_v1, kitgenix_hub_wporg_media_v1 (24 hours each).
• This lookup only runs when a logged-in administrator views the Kitgenix hub screen; it never runs on the front end and is unrelated to stock synchronisation.

No other third-party services, SaaS platforms, or analytics/tracking endpoints are contacted by this plugin.

Developer Reference

Text domain:
kitgenix-stock-sync-for-woocommerce

Option keys:
* kitgenix_stock_sync_for_woocommerce_settings
* kitgenix_stock_sync_for_woocommerce_snapshot_index (2.2.0+) – {sku: cached_at} index of last-known-good stock snapshots (capped at 1,000, entries older than 24 hours dropped), used by the Failover Readiness Report

Option schema (high-level):
* this_store_id, this_store_name, role, strict_checkout_validation, schema_version
* checkout_validation_failure_strategy (fail_open | fail_closed | stale_cache), checkout_stale_cache_minutes
* master (child config): url, store_id, secret, secret_previous, secret_previous_expires_at, health
* children (master config): entries with id, name, url, secret, secret_previous, secret_previous_expires_at, enabled, health
* exclusions.skus
* conflicts_report: {generated_at, items[]} – each item has type, sku, gid, child_id, child_name, master_value, child_value, detail
* sku_holds (2.2.0+): {sku: {reason, since, detail}} – SKUs held out of sync by the SKU Mapping Repair Tool
* identity_report (2.2.0+): {generated_at, items[]} – each item has type (duplicate_sku | duplicate_gid | missing_sku), sku, gid, blocking, hold_skus, products[], detail
* Diagnostics/admin UI state: notices, event_log, backlog (v2: id, type, store_id, attempt, status, next_retry_at, payload, payload_meta, error, code), reconcile (v2: mode, dry_run, differences_only, selected_skus, processed, total_estimate, differences_found, pushed_count, started_at, finished_at, last_batch_at), health (this store’s own global health, retained alongside the newer per-store master/children[].health)

Product/variation meta keys:
* _kitgenix_stock_sync_for_woocommerce_gid – stable cross-store identity, survives SKU renames. Never regenerated once set.
* _kitgenix_stock_sync_for_woocommerce_version – Master-authoritative monotonic version counter, bumped on every authoritative capture.
* _kitgenix_stock_sync_for_woocommerce_applied_version – last version a receiving store actually applied; the staleness-fencing guard.
* _kitgenix_stock_sync_for_woocommerce_history (2.2.0+) – Stock History per SKU: the most recent stock events for this product (default 20), each with time, type (captured | authoritative | applied | sku_rename | skipped_stale), version, stock_quantity, stock_status, backorders, context, store_id, event_id, note. Diagnostic only; sync never reads it.

WooCommerce’s “Duplicate” product action does not copy these keys to the new product (2.2.0+).

REST API routes (POST):
* /wp-json/kitgenix-stock-sync/v1/ping – returns wc_version and plugin_version; on a Child (2.2.0+) also failover, a non-secret readiness summary (checkout strategy, snapshot counts/ages, backlog counts) for the Master’s Failover Readiness Report
* /wp-json/kitgenix-stock-sync/v1/event
* /wp-json/kitgenix-stock-sync/v1/stock (master only; used by strict …