WooCommerce 11.2 introduce un filtru nou în Store API, woocommerce_store_api_cart_item_quantity_validation, care permite respingerea unei modificări de cantitate pentru un produs din coș. Filtrul rulează după verificările standard de minim, maxim și multiplu și returnează un obiect WP_Error atunci când cantitatea trebuie blocată. Este răspunsul oficial la o lipsă veche de ani de zile: blocul de coș și de checkout nu aveau un echivalent al filtrului din coșul clasic. Anunțul apare pe blogul pentru dezvoltatori WooCommerce, semnat de Shani Banerjee, pe 24 septembrie 2026.

Diferența față de vechiul sistem este simplă și dureroasă în același timp. Coșul clasic, cel cu shortcode, folosea woocommerce_update_cart_validation. Acolo funcționa tiparul clasic: apelezi wc_add_notice() cu un mesaj, returnezi false și clientul vede eroarea. În Store API, acest tipar nu se transferă. Filtrul nou ignoră complet notificările adăugate cu wc_add_notice(). Singurul mod de a respinge o cantitate este să returnezi un WP_Error. Orice altă valoare returnată, inclusiv false, este ignorată, iar cantitatea este acceptată. Este capcana principală pe care o semnalează chiar documentația.

Ce face, de fapt, filtrul nou

Filtrul woocommerce_store_api_cart_item_quantity_validation primește patru argumente: valoarea de validare, cantitatea cerută, obiectul produsului și elementul din coș. Rulează în două situații: când se actualizează cantitatea unui element existent în coș și când un produs aflat deja în coș este adăugat din nou. Nu rulează la prima adăugare a unui produs. Pentru acel caz există acțiunea separată woocommerce_store_api_validate_add_to_cart, care rezolvă altă etapă a fluxului.

Când filtrul returnează un WP_Error, Store API trimite codul și mesajul erorii într-un răspuns HTTP 400, iar interfața blocului afișează mesajul cumpărătorului. Exemplul din documentație limitează un produs la 3 bucăți per comandă: dacă $quantity depășește 3, filtrul returnează un WP_Error cu un mesaj formatat. Restul logicii rămâne neschimbat.

Există și o parte de compatibilitate care merită subliniată. Filtrul este aditiv. Fără callback-uri atașate, Store API se comportă exact ca înainte. Filtrul poate adăuga restricții, dar nu poate relaxa limitele declarate de minim, maxim sau multiplu. Dacă ai nevoie de limite numerice, ele se pun în filtrele woocommerce_store_api_product_quantity_*, nu aici. Iar woocommerce_update_cart_validation rămâne neschimbat și rulează în continuare doar pentru coșul cu shortcode.

De ce contează pentru magazinele care folosesc blocuri

Aici apare riscul real, și nu este unul teoretic. Multe extensii de ecommerce, de la reguli de cantitate pe categorie până la limitări de stoc sau oferte de tip "maximum 2 per client", s-au construit pe filtrul clasic. Dacă acel callback respinge cantități în coșul clasic, regula respectivă nu se aplică în blocul de coș. Orice client care folosește Cart block sau orice client care vorbește direct cu Store API ocolește regula fără să facă nimic special.

Documentația este explicită: un callback copiat ca atare din woocommerce_update_cart_validation va accepta fiecare modificare de cantitate. Nu vei vedea o eroare, nu vei vedea un log, pur și simplu regula nu se execută. Pentru un magazin care se bazează pe blocuri și pe un checkout modern, asta înseamnă că o regulă de business pe care o consideri activă poate să nu fie activă deloc.

Cei doi piloni trebuie ținuți împreună: filtrul vechi pentru coșul cu shortcode, filtrul nou pentru Store API și blocurile de coș și checkout. Sunt două coșuri diferite, cu două căi de execuție diferite, iar un magazin care le amestecă fără să știe poate ajunge cu reguli aplicate inconsistent între utilizatori.

Cum verifici dacă ești afectat

Primul pas este căutarea. Deschide directorul extensiilor și caută woocommerce_update_cart_validation. Dacă îl găsești și este folosit pentru a respinge modificări de cantitate, ai o problemă de acoperire: regula se aplică doar coșului clasic. Dacă folosești doar blocul de coș în magazin, regula nu se aplică deloc în practică.

Al doilea pas este testarea, și aici contează metoda. Modifică cantitatea în blocul de coș, depășind regula pe care o ai în callback-ul vechi, și verifică dacă eroarea apare. Dacă nu apare, filtrul nou nu este conectat. Testează și pe prima adăugare în coș, separat, pentru că acolo rulează altă acțiune.

Al treilea pas este implementarea. Adaugă un callback pe woocommerce_store_api_cart_item_quantity_validation, returnează WP_Error pentru cantitățile pe care le respingi și păstrează callback-ul vechi pentru coșul clasic. Cele două acoperă căi diferite, deci ambele rămân necesare dacă magazinul tău acceptă și shortcode.

Un detaliu de finețe: dacă un utilizator are un element în coș cu cantitatea deja setată, iar regula ta se schimbă ulterior, filtrul se execută la următoarea actualizare. Nu curăță retroactiv coșuri existente. Verifică fluxurile de checkout finalizat, nu doar starea coșului.

Pentru echipele care administrează platforme de comerț online, merită citit și materialul despre retail media și costul de oportunitate în ecommerce, pentru că regulile de coș influențează direct structura comenzilor și valoarea medie. Iar cine lucrează cu integrări de platformă poate corela și cu oprirea Global Catalog REST API pe 2 noiembrie 2026, un alt termen tehnic care afectează feedurile de produse.

Ce înseamnă pentru tine, ca antreprenor sau marketer român

Dacă rulezi un magazin online pe WooCommerce cu blocuri de coș și checkout, întrebarea nu este dacă filtrul nou este util. Întrebarea este câte reguli de business crezi că sunt active și nu sunt. Un magazin care limitează cantitatea per client, per categorie sau per promoție poate să creadă că protejează marja, iar în realitate să nu blocheze nimic.

Impactul practic se vede în trei zone. Prima este marja: o promoție cu cantitate limitată nu mai este limitată, iar clienții pot cumpăra în volum. A doua este logistica: comenzi cu cantități neașteptate, ambalare și livrare recalculate. A treia este experiența clientului: dacă anunți o limită în pagina produsului și coșul o ignoră, apare inconsistență între promisiune și comportament. Nu este vorba doar de cod, ci de credibilitatea ofertei.

Pentru marketerul care lucrează cu promoții sezoniere, momentul verificării este acum, nu în vârful campaniei. Testează coșul cu blocuri, testează adăugarea repetată a aceluiași produs și verifică dacă mesajul de eroare ajunge la client. Dacă ai o extensie terță care se ocupă de reguli de cantitate, întreabă furnizorul dacă a adăugat suportul pentru Store API. Nu presupune că actualizarea s-a făcut automat.

Aici intervine și partea de măsurare. Dacă regula de cantitate nu se aplică, datele din analytics arată altă structură de coș decât cea pe care o planifici. Rapoartele de valoare medie a comenzii se schimbă, iar deciziile de buget pe campanii se iau pe date care reflectă un comportament nefiltrat. Verificarea tehnică a coșului este, în acest context, o verificare de date de marketing.

Limite și ce nu rezolvă filtrul

Filtrul nou nu este o soluție de securitate. Nu previne frauda, nu validează plăți și nu înlocuiește regulile de stoc. Este un punct de control pe cantitate, în fluxul de coș. Dacă ai nevoie de control pe stoc, îl pui în altă parte. Nu este nici un mecanism de limitare pe client, ci unul pe cantitatea dintr-un element de coș.

Nu relaxează limitele declarate. Dacă un produs are maxim 5 declarat în filtrele de cantitate, filtrul nou nu poate să permită 7. Poate doar să respingă mai mult, nu să deschidă mai larg. Iar dacă ai un callback vechi care se baza pe wc_add_notice(), mesajul nu va ajunge la client prin filtrul nou. Trebuie reformulat ca WP_Error.

O verificare incompletă nu dovedește absența unei funcții. Dacă nu găsești woocommerce_update_cart_validation în extensii, nu înseamnă automat că nu ai nicio regulă de cantitate implementată altfel. Verifică și pluginurile de personalizare, snippet-urile din temă și codul custom din child theme. Rezultatul testului în blocul de coș este dovada, nu absența unui șir de caractere în căutare.

FAQ

Se aplică filtrul nou și pe coșul clasic? Nu. Filtrul woocommerce_store_api_cart_item_quantity_validation rulează în Store API, folosit de blocul de coș și de checkout. Coșul clasic rămâne pe woocommerce_update_cart_validation. Cele două acoperă căi diferite, deci ai nevoie de callback-uri separate dacă magazinul tău folosește ambele.

Ce se întâmplă dacă returnez false în loc de WP_Error? Cantitatea este acceptată. Filtrul ignoră orice altă valoare în afară de WP_Error. Notificările adăugate cu wc_add_notice() nu sunt citite. Trebuie să returnezi un obiect WP_Error pentru ca modificarea să fie respinsă.

Filtrul rulează la prima adăugare a unui produs în coș? Nu. Rulează când se actualizează cantitatea unui element existent sau când un produs aflat deja în coș este adăugat din nou. Pentru prima adăugare există acțiunea woocommerce_store_api_validate_add_to_cart.

Concluzie

WooCommerce 11.2 închide o lacună veche între coșul clasic și Store API, dar o închide cu o condiție: cine vrea să o folosească trebuie să scrie cod nou, nu să copieze callback-ul vechi. Pentru magazinele care rulează pe blocuri, diferența dintre o regulă de cantitate activă și una aparentă se rezolvă în câteva ore de verificare, nu în săptămâni de dezvoltare.

Un instrument AI poate ajuta la analiză, la citit cod, la generat un callback nou sau la planificat testele. Dar decizia despre ce reguli de business aplici în coș, cum le testezi și ce faci cu rezultatele rămâne a omului, media buyer sau dezvoltator, care înțelege fluxul comercial. Iar pasul concret, de la constatare la implementare verificată, îl face ALLSoft Agency. Fără hype, fără promisiuni de cifre, doar verificare și execuție.