Direct answer
To limit a WooCommerce product to a maximum quantity per cart, save one positive whole number on the product, expose it through WooCommerce's native quantity maximum, and validate both new additions and cart updates on the server. Count matching quantities already in the cart so separate requests cannot bypass the rule. Preserve any stricter stock or extension limit.
StoreFixKit's Maximum Quantity per Product for WooCommerce uses that bounded model. Free sets an explicit product value. Pro reuses one value by category or tag, adds product exceptions, and supports one customer-role override.
A cart limit is not stock management
“Maximum quantity” can mean several different jobs:
- maximum units of one product in the current cart;
- maximum units across the whole order;
- maximum units bought by one customer over time;
- remaining physical stock;
- quantity step or case pack;
- minimum and maximum combined.
These jobs need different data and failure boundaries. A per-cart plugin should not query order history, reserve inventory, change stock, or force package multiples. It answers one question: would this add or update place more than the saved number of this purchasable item in the current cart?
WooCommerce's official Min/Max Quantities product covers a much broader mix of product, order, and category rules. That breadth is useful for merchants who need it. It also shows why a small store with one simple cap can benefit from a narrower tool and a shorter test matrix.
Browser limits are helpful but not sufficient
Setting the quantity input's maximum improves the product-page experience. A shopper can still submit a crafted request, use a direct add URL, call the Store API, or combine several additions.
The server must validate:
- a new add-to-cart request;
- the quantity already present for the same product or variation;
- a classic cart update;
- the quantity maximum returned by the Store API;
- variation data used by the classic variable-product form.
When an oversized request arrives, reject that request and keep the previous valid cart. Do not reduce the quantity silently, empty the cart, or modify stock.
Count the purchasable variation correctly
For a simple product, the purchasable ID is the product ID. For a variable product, it is the selected variation ID. Two different variations can legitimately have different limits and different cart quantities.
The selected variation can use its own explicit value. When it has no value, a parent-product fallback gives the merchant one simple default. This avoids requiring a matrix for every variation while still allowing an exception where needed.
Never raise a stricter maximum
WooCommerce may already limit the input because only three units are in stock. Another extension may also provide a stricter maximum. If this plugin's saved value is five, the effective maximum must remain three.
The safe calculation is the stricter positive maximum, not the last filter to run. A focused limiter should never increase an existing cap or enable a product WooCommerce considers unavailable.
Why compatibility failures matter more than extra features
Public support threads include a fatal-error report around a product maximum helper and a compatibility report saying a minimum/maximum quantity plugin broke. Individual threads do not prove a universal defect, but they identify the cost of coupling a small rule to unstable helpers or too many unrelated behaviors.
A safer small plugin should use public WooCommerce filters, check that expected objects and methods exist, normalize malformed data, and return the original value when it cannot prove a valid limit.
Reusable category and tag rules need one clear priority
Pro can reduce repetitive editing while keeping an understandable precedence:
- an explicit Free product or variation value wins;
- a selected exception receives no Pro value;
- a category or tag match receives one reusable maximum;
- one selected customer role can receive one different maximum.
That model avoids a hidden “lowest of twelve rules” or “last matching rule wins” system. A merchant can inspect one product and know whether the explicit field or one shared assignment owns the result.
Store API and Cart Blocks
Cart and Checkout Blocks rely on WooCommerce's Store API. Returning the effective maximum through WooCommerce's public Store API quantity filter keeps the block interface aligned with the server rule.
The interface is still not the security boundary. Test a Store API request above the limit and verify the server preserves the existing cart. Then repeat through the live block cart UI.
Safety and resource boundary
The product page and cart already contain the product objects and quantities needed for this decision. The plugin needs no custom table, cron job, telemetry, frontend script, frontend stylesheet, remote request, or customer cookie.
It must not change:
- stock or backorders;
- product price or totals;
- coupons, tax, or shipping;
- payment methods;
- order status;
- previous customer purchases;
- refunds or subscriptions.
StoreFixKit's Maximum Quantity documentation contains the exact product field, variation behavior, Pro priority, rollback, and uninstall workflow.
Beginner launch checklist
Product input
Save a maximum of three. Confirm the product page does not offer a higher value through the native input.
New add
Add three, then try one more. The second request should fail and the existing three should remain.
Cart update
Try changing the cart line from three to four. The update should fail without changing other cart lines.
Repeated additions
Add one unit three times, then try a fourth. Multiple requests must not bypass the total.
Stock interaction
Set stock below the plugin maximum. The storefront must preserve the lower stock limit.
Variations
Test a variation-specific value, a parent fallback, and a different variation of the same parent.
Pro precedence
Test a shared category or tag rule, one exception, one explicit Free product, a guest, and the selected role.
Rollback
Deactivate Pro and verify explicit Free values still work. Deactivate Free and verify WooCommerce returns to its original stock and quantity rules without product or order repair.
Security and support evidence
Only users allowed to edit products should change the Free value, and only users who can manage WooCommerce should save Pro assignments. Product and settings writes need capability checks, nonces, integer bounds, sanitization, and escaped output. WordPress's common plugin issues guide explains the review expectations.
Useful support evidence includes the product and variation IDs, saved maximum, existing cart quantity, stock status, WooCommerce and plugin versions, cart type, expected result, actual result, and screenshots. Remove customer data, credentials, payment details, and full license keys.
FAQ
Is this a lifetime purchase limit?
No. It limits the current cart and does not inspect customer order history.
Does it reduce stock?
No. WooCommerce remains the owner of stock and reservations.
Can it set a minimum or a case-pack multiple?
No. Those are separate quantity jobs.
What if stock is lower than the saved maximum?
The stricter WooCommerce stock maximum remains in effect.
What happens when Pro expires?
Explicit Free product values continue working. Reusable Pro assignments and the role override require an active product-bound license.
Focused plugin
Use the one-job implementation.
Limit how many units of a selected WooCommerce product or variation can be in one cart without changing stock, prices, products, or orders.