WooCommerce's September 24, 2026 developer advisory introduces a Store API cart quantity validation filter for 11.2. Treat this as compatibility preparation for that release, not evidence that your current stable installation already supports it. Test the exact installed build and keep production on an approved release path.
What the advisory changes
The official quantity-validation advisory names woocommerce_store_api_cart_item_quantity_validation. It covers quantity updates and adding a product already present in the cart, after core numeric checks. First addition uses a different validation action.
The rejection contract matters: return a WP_Error. A copied legacy callback that adds a notice and returns false does not reject through this filter. The older shortcode-cart hook remains separate. This is a targeted extension point, not a replacement for every checkout or stock-validation rule.
Inventory the business rule before changing code
Write the actual requirement in plain language. Is the limit per product, variation, cart, customer, or time period? A three-item cap per line is not automatically a three-item cap across several variants. Identify who owns the rule and what the customer should see when it blocks a change.
Search your custom extension for the legacy quantity-validation hook, and record whether customers use Cart blocks, shortcode cart, or a custom Store API client. A site can expose more than one route during a migration. Do not assume a test on one cart proves the others behave identically.
Explanatory worksheet for your own test evidence. No customer results are represented.
Prepare a small boundary test matrix
| Scenario |
Expected business result |
Evidence |
| Add a product to an empty cart |
Valid first-add behavior |
Correct initial quantity and message |
| Increase an existing line within the limit |
Change accepted |
Display and returned cart agree |
| Increase beyond the custom limit |
Clear rejection |
Error and retained valid quantity |
| Add the same product again |
Combined quantity checked |
No silent bypass of the cap |
| Use a different variation |
Rule follows its defined scope |
Per-line versus cross-variant result |
| Repeat in shortcode cart |
Equivalent business policy |
Separate callback still works |
Use test products with harmless inventory and no live payment side effects. Record the exact WooCommerce package, extension revision, cart type, and starting cart contents for every run. Reset the fixture deliberately between tests; an old cart state can make a valid callback look inconsistent.
Keep the adapter small and explicit
Implement the same approved business policy through the relevant interfaces while respecting each interface's return contract. Where practical, separate the policy calculation from the adapter that produces a Store API error or legacy notice. Do not paste an example cap into production without deciding which products and customers it applies to.
Check another extension's existing rejection before replacing a result. A new rule must not accidentally erase a different valid restriction. Core quantity boundaries and custom policy also need a clear relationship: test both rather than trying to use the new callback to override every stock or numeric constraint.
Inspect the shopper's recovery path
After an invalid change, verify the customer sees an understandable message, the cart retains a valid state, and a permitted quantity can be submitted without reloading the whole journey. Check keyboard focus, mobile layout, totals, and any express purchase route your store supports.
If the failure is a billing or address field rather than cart quantity, use the existing Store API billing-validation guide. That query has its own owner and test path; adding more quantity hooks will not repair an address schema mismatch.
Release only after the compatibility evidence exists
Run the matrix against the intended supported release candidate or staging build, then repeat on the approved production version before enabling the integration. Keep a rollback for the custom extension and document the minimum compatible WooCommerce version. Recheck the vendor advisory if the release contract changes.
HandL WP WooCommerce repair can help when block and shortcode carts enforce different rules. Bring the policy, cart types, sanitized response, and failing fixture. A passing result means customers encounter the same intended business boundary through each supported cart, with a recoverable error when they exceed it.
References checked September 25, 2026. Illustrations and examples are explanatory, not customer case studies.