Shared Stock for OpenCart — one stock for several products and option values, no overselling

Shared Stock for OpenCart is a module by the CatCode studio for a store that sells one physical item in several places of its catalogue. A Vanilla bar on its own — and the same flavour in a gift box where the shopper picks a flavour in five lists, “Flavour 1…5”. The same item in another box. OpenCart keeps the stock of every product and every option value separately, so the store owner copies figures by hand — and still sells the last unit twice.

Shared Stock joins such places into a pool — one stock figure they all sell from. A pool member can be a whole product or a single option value. The cart is checked against the pool as a whole: a box with five “Vanilla” picks, quantity 2, takes 10 from the pool. A sale of any member takes from the pool, and every member shows how much the pool can still cover. Two shoppers confirming the last units in the same second do not both get them.

This is not a duplicate of Option Combinations. Option Combinations keeps the stock of option combinations inside one product (size × colour). Shared Stock covers a different scenario: one stock for different products and option values — the same flavour as a product of its own, in the five lists of a box and in another box. The first module does not share stock between products; the second does not track combinations inside a product.

What the shopper sees

The shopper picks the flavours in a box and presses “Add to Cart”. If, together with what is already in the cart, the pool is not enough, OpenCart does not add the product and a clear sentence appears above the button: how many are left, or that all of them are already in the cart. A value the pool can no longer cover disappears from the option list like any “out of stock” value.

If the pool went down while the product sat in the cart (another shopper bought first), the cart marks the line with *** and blocks checkout — the standard OpenCart behaviour for stock, only counted by the pool.

What the admin gets

• Catalog → Shared stock: pools with their stock, the units held by unconfirmed orders and what is available; creating a pool. An empty new pool takes the stock of the first member you add.
• Pool page: “Add / take (±N)” relative to the current figure — a delivery booked while orders come in is never lost; “Set to” for a stock count; the e-mail threshold (Pro); members with their OpenCart quantity; product search and adding a whole product or a single option value; the list of holds by unconfirmed orders.
• Product form: a line under the “Quantity” field with the pool name. A new figure in this field or in an option value quantity sets the pool, an old figure from a form opened long ago does not.
• “Re-sync quantities” — after a CSV import or another module that writes quantities directly: mirrors show the pool again, members of deleted products are removed.

How it works, step by step

1. You create a pool (for example “Vanilla”), set the stock and add members: the whole bar and the “Vanilla” value from every list of the box. The OpenCart quantity of every member becomes a mirror of the pool.
2. The shopper adds a product to the cart. The module counts how many units of each pool the whole cart asks for, taking into account what unconfirmed orders of other shoppers hold, and refuses with an explanation if there are not enough.
3. At the confirm step — as a request of its own or inside the OpenCart 4 checkout page and One Page — the module takes a database lock, checks the cart against the pool once more and holds the order units. Another shopper confirming in the same second waits for their turn and sees a smaller figure. If the queue takes longer than 10 seconds (configurable), the shopper gets a refusal rather than a risk of selling twice.
4. When the order enters a processing or complete status, the module takes the units from the pool — exactly once per order line — and updates the quantity of every member. Cancelling returns the units.
5. A hold of an unconfirmed order lives for 60 minutes (configurable); after that its units are available to other shoppers again.

What is tested and what is not

Tested locally on four OpenCart versions: 79 checks on OpenCart 4.1.0.3 and 4.0.2.3 and 77 each on 3.0.5.0 and 2.3.0.2 for the main scenario, plus separate runs in a browser, with One Page Checkout, order editing, imports and Pro e-mails. Version 1.0.1 went through the same set, plus five runs in a row of simultaneous checkout page loads (default and One Page) on OpenCart 4.1 and 4.0.2.3 — exactly 2 orders out of 8 every time, the pool never below zero — and 24 combinations of store language and shopper language for the “add to cart” message. Test servers stood in for the licence server and mail.

Limits worth knowing. The protection against simultaneous shoppers sits at the order confirm step — both when it runs as a request of its own and when OpenCart 4 or our One Page opens it inside the checkout page. A third-party one-page checkout that writes the order bypassing this step checks the cart without the lock; even then the module writes the hold only when the pool covers it. An order paid after its hold has expired (60 minutes by default) takes from the pool even below zero — just like OpenCart without the module; this shows in the pool history. Not tested: payment gateways with a bank callback, third-party one-page checkouts (other than ours), working together with Option Combinations, OpenCart 4 product variants (master / variant), MySQL 8 and Galera clusters.

Under the hood

• The pool lives in its own table. Member quantities in OpenCart only show how much the pool can still cover; checkout counts by the pool.
• One take per line. An order line takes from the pool once (a conditional update in the database), so a repeated status change or a repeated cancellation doubles nothing.
• Holding at confirmation. An order that reached the confirm step holds its units; the same shopper reopening the step replaces the hold instead of adding a second one.
• No core edits and no OCMOD patches — only OpenCart events; one library for three builds, code compatible with PHP 7.0, works with the pdo database driver of OpenCart 4.1 too.
• The licence is a separate settings group, so saving the settings does not touch it.
• Uninstall removes the module events and tables (you can keep the data for a reinstall).

How to install

1. OpenCart 4: Extensions → Installer → upload cc_sharedstock.ocmod.zip (do not rename the archive) and press “Install”. OpenCart 3: Extensions → Installer → cc_sharedstock-oc3.ocmod.zip → “Install”. OpenCart 2.3: Extensions → Installer → cc_sharedstock-oc2.ocmod.zip if FTP is enabled in the store settings; otherwise upload the contents of the upload/ folder from the archive to the store root.
2. Extensions → Extensions → Modules → Shared Stock → “Install”.
3. Catalog → Shared stock: create a pool and add members — a whole product or an option value.
4. Set the pool stock or leave the field empty — the pool then takes the stock of the first member you add.
5. For Pro: paste the licence key from the e-mail after payment, or start the trial on the “Licence” tab of the module settings.