WooCommerce 11.3 arregla el conteo de bundles en el carrito

En pocas palabras: WooCommerce 11.3, anunciado el 27 de octubre de 2026, permite declarar relaciones parent-child entre ítems del carrito mediante el filtro woocommerce_store_api_cart_item_parent_item_key y el campo parent_item_key en Store API, para que el bloque Product Button no cuente productos de bundles como agregados por separado.

WooCommerce anunció un cambio puntual para extensiones en la versión 11.3: se podrá declarar la relación parent-child cart item en WooCommerce mediante un nuevo filtro y un campo read-only en Store API, según el anuncio publicado en developer.woocommerce.com el 27 de octubre de 2026. El resultado: el bloque Product Button dejará de contar como «agregado por separado» un producto que en realidad vino adentro de un bundle.

El campo parent_item_key es un dato de solo lectura dentro de Store API de WooCommerce que indica si un ítem del carrito pertenece a otro ítem padre, como un producto incluido en un paquete o bundle. Lo declara el filtro woocommerce_store_api_cart_item_parent_item_key, que cada extensión tiene que implementar a mano: WooCommerce nunca marca esa relación por sí solo. El valor es un string con la clave del ítem padre, o null si no hay relación.

¿Qué problema resuelve el nuevo campo parent_item_key en WooCommerce 11.3?

Resuelve un bug de conteo visible para el comprador: si un producto llegaba al carrito solo porque formaba parte de un bundle, su botón de «Agregar al carrito» mostraba «1 in cart» aunque esa persona nunca lo haya tocado.

El problema de fondo es que Core no tenía forma de distinguir un ítem agregado de manera independiente de uno agregado como consecuencia de otro. ¿Y por qué importaba esto más allá de lo estético? Porque confundía al comprador sobre qué había elegido realmente, y porque si ese mismo producto aparecía en varias líneas de carrito, el bloque hidratado solo mostraba la cantidad de la primera línea, ignorando el resto.

Ejemplo hipotético: pensemos en una tienda que vende un «kit de limpieza» armado como bundle de tres productos: jabón, esponja y guantes. Si un comprador agrega el kit al carrito y después navega a la página del jabón vendido suelto, antes de la 11.3 el botón de ese jabón mostraría «1 in cart», como si lo hubiera elegido por su cuenta. Con el filtro implementado, el plugin de bundles declara que ese jabón es hijo del kit, y el Product Button deja de contarlo como una elección independiente. Es un escenario ilustrativo para entender el mecanismo, no un caso real reportado.

¿Cómo funciona el filtro woocommerce_store_api_cart_item_parent_item_key?

Funciona guardando la clave del ítem padre en los datos del ítem hijo y devolviéndola desde el filtro cuando WooCommerce la pide. La clave correcta es la que devuelve WC()->cart->add_to_cart(), no un ID de producto, eso es un detalle que conviene no pasar por alto.

El ejemplo que publica la propia documentación es este:

add_filter(
 'woocommerce_store_api_cart_item_parent_item_key',
 function ( $parent_item_key, $cart_item ) {
 return $cart_item['_my_extension_parent_item_key'] ?? $parent_item_key;
 },
 10,
 2
);

Ojo con un detalle: para cualquier ítem que no sea el tuyo, tenés que devolver $parent_item_key sin tocar. Si lo pisás con otro valor, le borrás la relación padre que haya declarado otra extensión, y ahí empiezan los dolores de cabeza de debugging cruzado entre plugins. Tampoco hace falta limpiar la clave guardada cuando el padre sale del carrito, eso lo maneja WooCommerce automáticamente.

¿Qué extensiones están afectadas por este cambio?

Están afectadas las extensiones que agregan ítems al carrito en nombre de otro ítem, según detalla el anuncio oficial de WooCommerce. La lista concreta que da la fuente:

• Bundles: cuando un paquete agrega productos individuales como componentes.
• Composite products: cuando el comprador armó una combinación y cada pieza entra como ítem separado.
• Mix and match: selecciones armadas que generan líneas de carrito por cada producto elegido.
• Force sells: productos que se agregan de forma forzada junto a otro.
• Chained products: encadenados a la compra de un producto principal.
• Frequently bought together: sugerencias que terminan sumando ítems vinculados al principal.

Los plugins de regalo gratis o de upsell quedan afuera de esta obligación. Si un cliente recibe un producto real atado a otro, «1 in cart» puede ser correcto para ese caso, así que la decisión queda en manos de quien desarrolla la extensión.

¿Cómo verifico si mi extensión necesita el nuevo filtro?

Se verifica agregando el producto padre al carrito y mirando el Product Button del producto que agregó por su cuenta. Si ese botón dice «1 in cart», tu extensión necesita el filtro.

Es un test rápido, nada de instrumentación rara. Agregás el bundle, abrís la página del producto hijo, mirás el contador. Si dice «1 in cart» cuando el comprador nunca lo tocó, ahí está el síntoma exacto que la documentación de WooCommerce describe como señal de que falta declarar la relación. Antes de subir el fix a producción, probá también el caso de cantidad múltiple del padre, para confirmar que el conteo del hijo suma todas las líneas y no solo la primera.

Para decidir si vale la pena invertir tiempo en esto, dos criterios simples:

• ¿El producto hijo se muestra o se vende también por separado? Si el comprador puede llegar a la página de ese producto fuera del contexto del bundle, el conteo erróneo es visible y conviene corregirlo. Si el componente nunca se vende suelto, el impacto visual es casi nulo.
• ¿Tu plugin ya oculta el botón o el contador para esos ítems hijos? Si ya lo escondés con CSS o lógica propia, adoptar el filtro no cambia nada visible hoy, aunque te deja mejor posicionado para cuando otros bloques dependan del mismo dato.

¿Qué pasa si no adopto el filtro parent_item_key?

No pasa nada roto: los ítems siguen contándose exactamente como lo hacían antes de WooCommerce 11.3. El cambio es opcional, no un breaking change, así que no hay fecha límite de migración forzada.

Eso sí, hay un costo de oportunidad. La fuente oficial aclara que el Product Button es, por ahora, el único lugar que usa parent_item_key, pero la idea es que otros bloques dependan de ese dato más adelante, por ejemplo el Cart y el Mini-Cart mostrando ítems hijos indentados bajo su padre. Si tu extensión sigue sin declarar la relación cuando eso llegue, te vas a quedar afuera de esa mejora de UX sin siquiera tener que hacer un cambio grande hoy.

Errores comunes al implementar el filtro parent_item_key

• Guardar el ID de producto en vez de la clave del carrito: el filtro espera la clave que devuelve add_to_cart(), no el product ID. Si guardás el ID, WooCommerce no va a encontrar coincidencia y va a devolver null.
• Pisar el valor de otros ítems: si tu callback devuelve un valor fijo sin chequear primero si el ítem es el tuyo, le borrás la relación declarada por otra extensión que corrió antes en la cadena de filtros.
• Dar por hecho que el padre siempre está presente: si el comprador elimina el producto padre, la clave del hijo vuelve a null sola. No hace falta (ni conviene) tratar de forzar esa limpieza desde tu código.
• Testear solo con un producto en el carrito: el bug de conteo con múltiples líneas es justamente lo que corrige esta versión, así que probar con una sola unidad no te muestra si tu implementación suma bien las cantidades.

Si tu tienda corre bundles o composite products de alto volumen, vale la pena probar este fix en un entorno de staging antes de tocar producción. Para eso, un hosting WordPress de Donweb con ambiente de pruebas separado te permite validar el comportamiento del carrito sin arriesgar ventas reales mientras ajustás el filtro.

Preguntas Frecuentes

¿Qué es parent_item_key en WooCommerce?

Es un campo read-only de Store API, agregado en WooCommerce 11.3, que guarda la clave del ítem padre de un ítem del carrito o null si no tiene padre. Lo declaran las extensiones mediante el filtro woocommerce_store_api_cart_item_parent_item_key, no lo asigna WooCommerce por defecto.

¿Necesito actualizar mi plugin de bundles por este cambio?

Depende del resultado del test del Product Button: si al agregar el producto padre, el botón del hijo marca «1 in cart», conviene actualizar el plugin para usar el nuevo filtro. Si tu plugin ya oculta o no muestra ese contador para componentes de bundle, no hay urgencia.

¿Rompe algo en producción no adoptar el filtro?

No, según confirma el anuncio oficial: los ítems sin la relación declarada siguen contándose igual que antes de la versión 11.3. Es un cambio aditivo, no un breaking change.

¿Qué clave hay que guardar en el filtro, el ID del producto o la clave del carrito?

Hay que guardar la clave del ítem del carrito, la misma que devuelve WC()->cart->add_to_cart() cuando se agrega el producto padre. Usar el ID del producto en su lugar hace que WooCommerce no encuentre coincidencia y devuelva null.

¿Qué bloques usan parent_item_key por ahora?

Por ahora solo el conteo «N in cart» del bloque Product Button lo usa, según el anuncio de WooCommerce. La documentación oficial menciona que a futuro bloques como Cart y Mini-Cart podrían usarlo para mostrar ítems hijos indentados bajo su padre.

Conclusión

WooCommerce 11.3 no trae una funcionalidad vistosa para el comprador final, trae un dato puntual (parent_item_key) que le da a cada extensión la posibilidad de decir «este ítem es parte de otro». Si desarrollás o mantenés un plugin de bundles, composite products, mix and match, force sells, chained products o frequently bought together, el paso concreto es correr el test del Product Button esta semana y, si corresponde, sumar el filtro con la clave de carrito correcta.

Si no es tu caso, no hay nada que hacer ahora. El cambio es opcional y retrocompatible, pero conviene tenerlo en el radar porque WooCommerce ya avisó que futuros bloques como Cart y Mini-Cart podrían depender de esta misma relación padre-hijo.

Fuentes

• Declaring parent-child cart item relationships in WooCommerce 11.3 – anuncio oficial de WooCommerce Developer Blog